Chaindoc Webhooks

Otrzymuj powiadomienia w czasie rzeczywistym, gdy w twoim koncie Chaindoc wystąpią jakieś zdarzenia. Webhooki natychmiast przesyłają dane o zdarzeniach na twój serwer, eliminując potrzebę odpytywania.

Wymagania

Subskrypcja planu Business (tylko użytkownicy planu Business mogą konfigurować webhooki) Punkt końcowy HTTPS na twoim serwerze Publicznie dostępny adres URL (webhooki nie mogą być wysyłane do localhost)

Przegląd

Chaindoc Webhooks umożliwiają twojej aplikacji otrzymywanie powiadomień w czasie rzeczywistym, gdy na twoim koncie zachodzą określone zdarzenia. Zamiast odpytywać API, webhooks przesyłają dane o zdarzeniach do twojego serwera natychmiast po wykonaniu danej czynności.

Najważniejsze cechy

Powiadomienia w czasie rzeczywistym — natychmiastowe dostarczanie informacji o zdarzeniach na twój serwer
Automatyczne ponowne próby — do 3 ponownych prób z wykładniczym opóźnieniem
Weryfikacja podpisu — HMAC SHA256 w celu zapewnienia autentyczności danych użytkowych
Filtrowanie wydarzeń — otrzymuj tylko te wydarzenia, które cię interesują
Śledzenie błędów — monitoruj status dostarczania webhooków i awarie

Przykłady zastosowań

Wysyłaj powiadomienia e-mailowe po podpisaniu dokumentów
Uruchamiaj przepływy pracy po zweryfikowaniu dokumentów w łańcuchu bloków.
Aktualizuj bazę danych po utworzeniu wniosków o podpisanie
Synchronizuj status dokumentu z systemami zewnętrznymi
Ścieżka audytu i rejestrowanie zgodności

Konfiguracja

Krok 1: Utwórz klucz API

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

Krok 2: Skonfiguruj adres 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 webhooka

Utwórz punkt końcowy na swoim serwerze, aby odbierać zdarzenia 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);

Rodzaje wydarzeń

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

document.created

Uruchamiane po utworzeniu nowego dokumentu za pośrednictwem API.

terminal

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

document.verified

Uruchamiane po pomyślnej weryfikacji dokumentu w łańcuchu bloków.

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

Uruchamiane po zebraniu wszystkich wymaganych podpisów.

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

Uruchamiane po utworzeniu nowego żądania 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

Uruchamiane, gdy wszyscy sygnatariusze zakończą podpisywanie.

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

Uruchamiane, 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 podpisu

Chaindoc podpisuje wszystkie ładunki webhooków za pomocą HMAC SHA256. Zawsze weryfikuj podpisy, aby zapewnić autentyczność i zapobiec atakom typu replay.

Najlepsze praktyki w zakresie bezpieczeństwa

Zawsze używaj funkcji porównawczych bezpiecznych pod względem czasowym. Nigdy nie pomijaj weryfikacji podpisu w produkcji. Zabezpiecz swój sekretny klucz webhooka Okresowo zmieniaj hasła Korzystaj wyłącznie z punktów końcowych HTTPS.

Jak działa weryfikacja podpisu

1Chaindoc tworzy podpisChaindoc tworzy podpis HMAC przy użyciu twojego sekretnego klucza webhook.

2Podpis wysłany w nagłówkuPodpis jest wysyłany w nagłówku X-Webhook-Signature.

3Twój serwer weryfikujeTwój serwer ponownie oblicza podpis i porównuje go za pomocą funkcji zabezpieczającej przed zmianą czasu.

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 ponownej próby

Chaindoc automatycznie ponawia nieudane dostawy webhooków z wykładniczym opóźnieniem.

Pierwsza ponowna próba: po 1 minucie
Druga próba: po 5 minutach (łącznie: 6 minut)
Trzecia próba: po 15 minutach (łącznie: 21 minut)

Kryteria sukcesu

Twój punkt końcowy zwraca kod statusu HTTP 200-299 Twój punkt końcowy odpowiada w ciągu 30 sekund Podczas dostarczania nie występują żadne błędy sieciowe

Testowanie webhooków

Rozwój lokalny

Użyj narzędzi takich jak ngrok, aby udostępnić 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 ręczne

Przetestuj punkt końcowy webhooka za pomocą przykładowego ładunku:

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 podpisy webhooków przed przetworzeniem
Odpowiadaj szybko (w ciągu 30 sekund), aby uniknąć przekroczenia limitu czasu.
Przetwarzaj webhooki asynchronicznie w kolejce
Wprowadź idempotencję, aby obsługiwać zduplikowane zdarzenia.
Rejestruj wszystkie zdarzenia webhooków w celu debugowania i audytu.
Monitoruj błędy dostarczania webhooków w swoim panelu kontrolnym.
Ze względów bezpieczeństwa używajcie punktów końcowych HTTPS.
Obsługuj wszystkie typy zdarzeń w sposób elegancki (ignoruj nieznane zdarzenia).

Pełny przykład

Oto gotowy do użycia moduł obsługi webhooków 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.documentId },
    data: {
      status: 'verified',
      blockchainTxHash: payload.txHash,
      verifiedAt: new Date(payload.timestamp),
    },
  });
}

async function handleSignatureCompleted(payload: any) {
  await prisma.signatureRequest.update({
    where: { id: payload.signatureRequestId },
    data: {
      status: 'completed',
      completedAt: new Date(payload.completedAt),
    },
  });
}

function verifySignature(payload: any, signature: string, secret: string): boolean {
  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);

Kolejne kroki

Skonfiguruj adres URL webhooka w panelu Chaindoc. Podczas tworzenia oprogramowania przeprowadź testy za pomocą ngrok. Monitoruj dostarczanie webhooków w swoich logach Skonfiguruj powiadomienia o nieudanych dostawach

Documentation