Chaindoc logoChaindoc

Webhooks w Chaindoc

Webhooks wysyłają dane o zdarzeniach na Twój serwer w momencie, gdy coś dzieje się w Chaindoc. Bez odpytywania, bez opóźnień. Na tej stronie znajdziesz informacje o konfiguracji, typach zdarzeń, weryfikacji HMAC, logice ponawiania i testowaniu.

Przegląd

Zamiast odpytywać API, webhooks informują Twój serwer o tym, co się wydarzyło, natychmiast po zdarzeniu. W praktyce wykorzystasz je do synchronizacji statusu dokumentów, uruchamiania workflow po podpisach, wysyłania powiadomień i utrzymywania bazy danych w synchronizacji.

  • Natychmiastowa dostawa z maksymalnie 3 automatycznymi ponowieniami (exponential backoff)
  • Weryfikacja sygnatury HMAC SHA256 dla każdego payloadu
  • Filtrowanie tylko do interesujących Cię typów zdarzeń
  • Śledzenie statusu dostawy w panelu administracyjnym

Konfiguracja

Krok 1: Utwórz klucz API

Przejdź do Ustawienia → Dostęp API w panelu Chaindoc i utwórz klucz API z włączoną konfiguracją webhooków.

Krok 2: Skonfiguruj URL webhooka

Użyj API, aby skonfigurować punkt końcowy webhooka:

terminal
curl -X PATCH https://api.chaindoc.io/user/api-access/1/config \
  -H "Authorization: Bearer your_auth_token" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookUrl": "https://yourapp.com/webhooks/chaindoc",
    "webhookEnabled": true,
    "webhookSecret": "your_secure_random_string"
  }'

Krok 3: Zaimplementuj punkt końcowy

Utwórz punkt końcowy na swoim serwerze do odbierania zdarzeń webhook. Oto przykłady w różnych językach:

const express = require('express');
const crypto = require('crypto');

const app = express();
app.use(express.json());

app.post('/webhooks/chaindoc', (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const eventType = req.headers['x-webhook-event'];
  
  // Verify signature
  if (!verifySignature(req.body, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }
  
  // Process event
  console.log('Received event:', eventType, req.body);
  
  // Handle different event types
  switch (eventType) {
    case 'document.created':
      handleDocumentCreated(req.body);
      break;
    case 'document.verified':
      handleDocumentVerified(req.body);
      break;
    case 'signature.request.completed':
      handleSignatureCompleted(req.body);
      break;
  }
  
  // Always respond with 200 OK
  res.status(200).send('Webhook received');
});

function verifySignature(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const digest = hmac.update(JSON.stringify(payload)).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(digest)
  );
}

app.listen(3000);

Typy zdarzeń

Chaindoc wysyła webhooki dla następujących zdarzeń:

document.created

Wywoływane, gdy nowy dokument jest tworzony przez API.

terminal
{
  "event": "document.created",
  "documentId": "86840ee4-8bf2-4a91-a289-e99d8307ec25",
  "name": "Service Agreement",
  "timestamp": "2024-12-04T10:30:00.000Z"
}

document.verified

Wywoływane, gdy dokument zostaje pomyślnie zweryfikowany na blockchain.

terminal
{
  "event": "document.verified",
  "documentId": "86840ee4-8bf2-4a91-a289-e99d8307ec25",
  "versionId": "f0b7721f-0399-4035-9b69-7b95d3a367f0",
  "txHash": "0x789ghi...",
  "chainId": 137,
  "timestamp": "2024-12-04T10:35:00.000Z"
}

document.signed

Wywoływane, gdy wszystkie wymagane podpisy zostaną zebrane.

terminal
{
  "event": "document.signed",
  "documentId": "86840ee4-8bf2-4a91-a289-e99d8307ec25",
  "signatureRequestId": "req_21096b94498f4a2d9795e810edc2c9a9",
  "signers": [
    {
      "email": "signer1@example.com",
      "signedAt": "2024-12-04T10:30:00.000Z"
    },
    {
      "email": "signer2@example.com",
      "signedAt": "2024-12-04T10:32:00.000Z"
    }
  ],
  "timestamp": "2024-12-04T10:32:00.000Z"
}

signature.request.created

Wywoływane, gdy tworzone jest nowe żądanie podpisu.

terminal
{
  "event": "signature.request.created",
  "signatureRequestId": "req_21096b94498f4a2d9795e810edc2c9a9",
  "documentId": "86840ee4-8bf2-4a91-a289-e99d8307ec25",
  "recipients": [
    {"email": "signer1@example.com"},
    {"email": "signer2@example.com"}
  ],
  "deadline": "2024-12-31T23:59:59.000Z",
  "timestamp": "2024-12-04T10:30:00.000Z"
}

signature.request.completed

Wywoływane, gdy wszyscy podpisujący zakończą proces podpisywania.

terminal
{
  "event": "signature.request.completed",
  "signatureRequestId": "req_21096b94498f4a2d9795e810edc2c9a9",
  "documentId": "86840ee4-8bf2-4a91-a289-e99d8307ec25",
  "completedAt": "2024-12-04T10:32:00.000Z",
  "timestamp": "2024-12-04T10:32:00.000Z"
}

signature.request.rejected

Wywoływane, gdy podpisujący odrzuca żądanie podpisu.

terminal
{
  "event": "signature.request.rejected",
  "signatureRequestId": "req_21096b94498f4a2d9795e810edc2c9a9",
  "documentId": "86840ee4-8bf2-4a91-a289-e99d8307ec25",
  "rejectedBy": "signer1@example.com",
  "reason": "Terms not acceptable",
  "timestamp": "2024-12-04T10:30:00.000Z"
}

Bezpieczeństwo

Weryfikacja sygnatury

Chaindoc podpisuje wszystkie webhooki używając HMAC SHA256. Zawsze weryfikuj sygnatury, aby zapewnić autentyczność i zapobiec atakom powtórzeniowym.

Jak działa weryfikacja

1Chaindoc tworzy sygnaturęChaindoc generuje sygnaturę HMAC używając Twojego sekretu webhooka

2Sygnatura wysyłana w nagłówkuSygnatura jest wysyłana w nagłówku X-Webhook-Signature

3Twój serwer weryfikujeTwój serwer przelicza sygnaturę i porównuje używając funkcji chroniącej przed atakami timing

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const digest = hmac.update(JSON.stringify(payload)).digest('hex');
  
  // Use timing-safe comparison to prevent timing attacks
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(digest)
  );
}

// Usage
const isValid = verifyWebhookSignature(
  req.body,
  req.headers['x-webhook-signature'],
  process.env.WEBHOOK_SECRET
);

if (!isValid) {
  return res.status(401).send('Invalid signature');
}

Logika ponawiania

Chaindoc automatycznie ponawia nieudane dostawy webhooków z wykorzystaniem exponential backoff.

  • 1. ponowienie: Po 1 minucie
  • 2. ponowienie: Po 5 minutach (łącznie: 6 minut)
  • 3. ponowienie: Po 15 minutach (łącznie: 21 minut)

Testowanie webhooków

Lokalny development

Szczerze mówiąc, lokalne testowanie webhooków bez narzędzi zewnętrznych bywa kłopotliwe. Użyj ngrok, aby wystawić swój lokalny serwer do testowania webhooków:

terminal
# Install ngrok
npm install -g ngrok

# Start your local server
node server.js

# Expose port 3000
ngrok http 3000

# Use the ngrok URL as your webhook endpoint
# Example: https://abc123.ngrok.io/webhooks/chaindoc

Testowanie manualne

Przetestuj swój punkt końcowy webhook z przykładowym payloadem:

terminal
curl -X POST https://yourapp.com/webhooks/chaindoc \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Event: document.created" \
  -H "X-Webhook-Signature: test_signature" \
  -d '{
    "event": "document.created",
    "documentId": "test-123",
    "name": "Test Document",
    "timestamp": "2024-12-04T10:30:00.000Z"
  }'

Najlepsze praktyki

  • Zawsze weryfikuj sygnatury webhooków przed przetwarzaniem
  • Odpowiadaj szybko (poniżej 30 sekund), aby uniknąć timeoutów
  • Przetwarzaj webhooki asynchronicznie w kolejce
  • Wdrażaj idempotentność, aby obsługiwać zduplikowane zdarzenia
  • Loguj wszystkie zdarzenia webhook do debugowania i audytu
  • Monitoruj nieudane dostawy webhooków w panelu administracyjnym
  • Używaj punktów końcowych HTTPS ze względów bezpieczeństwa
  • Obsługuj wszystkie typy zdarzeń poprawnie (ignoruj nieznane zdarzenia)

Przykład produkcyjny

Oto produkcyjny handler webhook z integracją bazy danych:

webhooks/chaindoc.ts
import express from 'express';
import crypto from 'crypto';
import { PrismaClient } from '@prisma/client';

const app = express();
const prisma = new PrismaClient();

app.use(express.json());

app.post('/webhooks/chaindoc', async (req, res) => {
  const signature = req.headers['x-webhook-signature'] as string;
  const eventType = req.headers['x-webhook-event'] as string;
  const payload = req.body;
  
  // 1. Verify signature
  if (!verifySignature(payload, signature, process.env.WEBHOOK_SECRET!)) {
    console.error('Invalid webhook signature');
    return res.status(401).json({ error: 'Invalid signature' });
  }
  
  // 2. Check for duplicate events (idempotency)
  const eventId = `${eventType}-${payload.timestamp}`;
  const existing = await prisma.webhookEvent.findUnique({
    where: { eventId },
  });
  
  if (existing) {
    console.log('Duplicate event, skipping:', eventId);
    return res.status(200).json({ status: 'duplicate' });
  }
  
  // 3. Store event
  await prisma.webhookEvent.create({
    data: {
      eventId,
      eventType,
      payload,
      processedAt: new Date(),
    },
  });
  
  // 4. Process event asynchronously
  processWebhookAsync(eventType, payload).catch((error) => {
    console.error('Error processing webhook:', error);
  });
  
  // 5. Respond immediately
  res.status(200).json({ status: 'received' });
});

async function processWebhookAsync(eventType: string, payload: any) {
  switch (eventType) {
    case 'document.verified':
      await handleDocumentVerified(payload);
      break;
    case 'signature.request.completed':
      await handleSignatureCompleted(payload);
      await sendNotificationEmail(payload);
      break;
    case 'signature.request.rejected':
      await handleSignatureRejected(payload);
      break;
  }
}

async function handleDocumentVerified(payload: any) {
  await prisma.document.update({
    where: { id: payload.documen

Co zrobić dalej