Webhook
Vérifiez, transformez et (optionnellement) abonnez-vous aux webhooks d'un fournisseur.
Pour les fournisseurs qui envoient des webhooks vers la plateforme — vérifiez la signature, transformez le corps et gérez optionnellement le cycle de vie des abonnements.
Définir la capacité
import { defineCapabilityWebhook } from "@scrydon/sdk-authoring/integrations/define";
const webhookCapability = defineCapabilityWebhook({
// 1. Vérifier l'authenticité du webhook entrant
async verify(request) {
const signature = request.headers["x-webhook-signature"];
const isValid = verifyHmac(request.rawBody, signature, request.secret);
return { valid: isValid, error: isValid ? undefined : "Invalid signature" };
},
// 2. Transformer le corps brut en données structurées
async transform(body, context) {
const event = body as { type: string; data: unknown };
return { eventType: event.type, data: event.data, timestamp: Date.now() };
},
// 3. (Optionnel) Cycle de vie des abonnements
subscription: {
async subscribe(request) {
const response = await fetch("https://api.example.com/webhooks", {
method: "POST",
headers: { Authorization: `Bearer ${request.credentials.accessToken}` },
body: JSON.stringify({ url: request.webhookUrl, events: request.events }),
});
const data = await response.json();
return { subscriptionId: data.id, expiresAt: new Date(data.expiresAt) };
},
async unsubscribe(subscriptionId, credentials) {
await fetch(`https://api.example.com/webhooks/${subscriptionId}`, {
method: "DELETE",
headers: { Authorization: `Bearer ${credentials.accessToken}` },
});
},
},
// 4. Idempotence — prévenir le traitement en double
extractIdempotencyKey(headers, body) {
return headers["x-webhook-delivery-id"] ?? null;
},
});Obligatoire ou optionnel
| Méthode | Obligatoire | Objectif |
|---|---|---|
verify | oui | Rejeter les webhooks falsifiés ou rejoués avant qu'ils n'atteignent le workflow |
transform | oui | Formater le corps en payload de déclencheur attendu par vos blocs |
subscription.subscribe / unsubscribe | non | À implémenter uniquement si l'API du fournisseur prend en charge l'abonnement programmatique |
extractIdempotencyKey | non | Sans cela, les nouvelles tentatives du fournisseur peuvent déclencher des workflows deux fois |