Scrydon

Webhook

Vérifiez, transformez, abonnez, interrogez, testez et formatez les webhooks d'un fournisseur avec une seule capacité.

Utilisez la capacité webhook pour les fournisseurs qui envoient des événements vers la plateforme. Chaque implémentation vérifie et transforme les événements entrants. Les méthodes optionnelles couvrent les défis de validation, la correspondance des déclencheurs, l'idempotence, le cycle de vie des abonnements, l'interrogation de secours, les payloads de test et les réponses propres au fournisseur.

Définir la capacité

import { defineCapabilityWebhook } from "@scrydon/sdk-authoring/extensions/authoring/define";

const webhookCapability = defineCapabilityWebhook({
  async verify(request) {
    const signature = request.headers["x-webhook-signature"];
    const valid = verifyHmac(request.rawBody, signature, request.secret);
    return { valid, error: valid ? undefined : "Invalid signature" };
  },

  async transform(body, context) {
    const event = body as { id: string; type: string; data: unknown };
    return { id: event.id, eventType: event.type, data: event.data };
  },

  async challengeHandler(request) {
    const token = new URL(request.url).searchParams.get("challenge");
    return token ? new Response(token, { status: 200 }) : null;
  },

  matchEvent(event, trigger) {
    return event.eventType === trigger.config.eventType;
  },

  subscription: {
    async subscribe(request) {
      return createVendorSubscription(request);
    },
    async renew(subscriptionId, request) {
      return renewVendorSubscription(subscriptionId, request);
    },
    async unsubscribe(subscriptionId, credentials) {
      await deleteVendorSubscription(subscriptionId, credentials.accessToken);
    },
  },

  extractIdempotencyKey(headers) {
    return headers["x-webhook-delivery-id"] ?? null;
  },

  async buildTestPayload(request) {
    return {
      status: 200,
      payload: { type: "webhook.test", webhookId: request.webhookId },
    };
  },

  polling: {
    async initialize(request) {
      return { cursor: { since: new Date().toISOString() } };
    },
    async poll(request) {
      return pollVendorEvents(request.credentials.accessToken, request.cursor);
    },
  },

  responseFormatter: {
    formatSuccess() {
      return new Response(null, { status: 202 });
    },
    formatError(error) {
      return Response.json({ error: error.message }, { status: 400 });
    },
  },
});

subscribe, renew, les méthodes d'interrogation et de test reçoivent les identifiants résolus pour le tenant courant dans la frontière d'exécution de la plateforme. Ne les persistez, ne les journalisez et ne les retournez jamais. verify reçoit séparément le secret webhook configuré afin qu'une requête entrante ne puisse pas fournir elle-même la valeur utilisée pour l'authentifier.

Surface complète des méthodes

La plateforme associe chaque méthode d'authoring à une opération fermée et typée. Le code applicatif doit utiliser la capacité au lieu de charger les archives fournisseur ou d'appeler directement leurs utilitaires.

Méthode d'authoringObligatoireOpération de plateformeObjectif
verifyouiextensions.webhooks.verifyAuthentifier la requête brute avant son traitement
transformouiextensions.webhooks.transformConvertir le corps fournisseur en événement de workflow
challengeHandlernonextensions.webhooks.challengeRépondre aux défis de validation du fournisseur
matchEventnonextensions.webhooks.matchDéterminer si un événement correspond à un déclencheur configuré
extractIdempotencyKeynonextensions.webhooks.idempotency.extractDériver une identité de livraison stable pour dédupliquer les nouvelles tentatives
subscription.subscribenonextensions.webhooks.subscriptions.createCréer un abonnement fournisseur
subscription.renewnonextensions.webhooks.subscriptions.renewRenouveler un abonnement arrivant à expiration
subscription.unsubscribenonextensions.webhooks.subscriptions.deleteSupprimer un abonnement fournisseur
polling.initializenonextensions.webhooks.polling.initializeÉtablir le premier curseur d'interrogation
polling.pollnonextensions.webhooks.pollRécupérer les événements lorsque la livraison push n'est pas disponible
buildTestPayloadnonextensions.webhooks.test.buildConstruire un événement de test adapté au fournisseur
responseFormatternonextensions.webhooks.response.formatFormater les accusés de réception de succès ou d'erreur

Lorsqu'une méthode optionnelle est absente, elle renvoie explicitement not_supported à la frontière de la plateforme. Les erreurs du fournisseur restent des erreurs ; elles ne sont pas interprétées comme une capacité non prise en charge ni comme un succès implicite.

Valeurs à l'exécution

  • WebhookSubscription.expiresAt est un Date dans le code d'authoring. La frontière du worker le sérialise en horodatage ISO 8601 pour les appelants de la plateforme.
  • Les méthodes de défi et de formatage de réponse peuvent retourner un Response standard. Le statut, les en-têtes et le corps sont sérialisés à travers la frontière du worker.
  • transform peut retourner null pour ignorer volontairement un événement.
  • L'interrogation retourne payloads, le prochain curseur changes et apiCallCount ; gardez le curseur sérialisable en JSON, car il est persisté entre les exécutions.
Sur cette page

Sur cette page