Webhooks

Utilisez les webhooks pour réagir aux changements asynchrones. La livraison est au moins une fois, donc les événements dupliqués, retardés et hors ordre sont normaux.

N’enregistrez que les événements dont vous avez besoin

Créez un endpoint avec POST /v3/webhooks. Abonnez-vous uniquement aux événements documentés qui pilotent votre intégration. Cet exemple utilise transfer.state_changed.

Create webhook endpoint

export API_BASE='https://platform.swipelux.com'
export SWIPELUX_API_KEY='replace-with-your-api-key'

curl --request POST \
  "${API_BASE}/v3/webhooks" \
  --header "X-API-Key: ${SWIPELUX_API_KEY}" \
  --header "Idempotency-Key: webhook-endpoint-001" \
  --header "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "url": "https://example.com/webhooks/swipelux",
  "events": ["transfer.state_changed"]
}
JSON

Stockez le data.id de la réponse en tant que WEBHOOK_ID. Demandez une URL de portail à GET /v3/webhooks/portal avec une clé API disposant de webhooks:write, récupérez le secret de signature de cet endpoint et stockez-le séparément de votre clé API dans un gestionnaire de secrets. L’URL du portail donne accès à elle seule et expire au bout d’une heure : demandez-en donc une nouvelle à chaque fois, et ne la stockez ni ne la partagez. Le portail regroupe les événements v3 par ressource : Customers, Capabilities, Accounts, Recipients, Transfers et API. Chaque événement affiche son schéma de payload et un exemple. Les événements hérités sont marqués comme obsolètes et répertoriés dans un groupe Legacy distinct. Si votre endpoint est déjà abonné à un événement hérité, il continue de le recevoir. Choisissez des noms d’événements v3 pour les nouveaux abonnements.

Modifier les événements d’un endpoint

Lisez un endpoint avec GET /v3/webhooks/{webhookId}. La réponse a la même forme events que GET /v3/webhooks. Elle n’inclut jamais le secret de signature. Les lectures nécessitent webhooks:read et renvoient 404 not_found pour un ID d’endpoint inconnu. Mettez à jour l’endpoint avec PATCH /v3/webhooks/{webhookId}. Envoyez un en-tête Idempotency-Key. Les mises à jour nécessitent webhooks:write.

Envoyez uniquement events pour conserver l’URL actuelle.
Envoyez uniquement url pour conserver la sélection d’événements actuelle.
events remplace toute la sélection. Lisez d’abord l’endpoint et incluez chaque événement dont vous avez encore besoin.
Les nouveaux abonnements doivent utiliser des noms d’événements v3.
Vous pouvez conserver un nom d’événement hérité si l’endpoint y est déjà abonné. L’ajout d’un nouveau nom hérité renvoie 400 validation_error.

Ce corps conserve l’URL et remplace la sélection :

Request body

{
  "events": ["transfer.state_changed", "capability.status_changed"]
}

Vérifier avant l’analyse

Swipelux livre les nouvelles intégrations de webhooks via Svix. Vérifiez le corps brut de la requête avec le secret de signature de votre endpoint et ces en-têtes :

svix-id
svix-timestamp
svix-signature

N’analysez pas le JSON et ne provoquez aucun effet secondaire avant que la vérification ne réussisse.

Verify signature

import { Webhook } from "svix";

const verifier = new Webhook(process.env.SWIPELUX_WEBHOOK_SECRET);

export async function handleSwipeluxWebhook(request) {
  const rawBody = await request.text();
  const event = verifier.verify(rawBody, {
    "svix-id": request.headers.get("svix-id"),
    "svix-timestamp": request.headers.get("svix-timestamp"),
    "svix-signature": request.headers.get("svix-signature"),
  });

  await webhookInbox.insertIfAbsent({
    id: event.id,
    payload: event,
    status: "pending",
  });

  return new Response(null, { status: 204 });
}

Rejetez les requêtes avec des signatures manquantes ou invalides. Gardez le corps brut disponible jusqu’à ce que la vérification soit terminée.

Persister, acquitter, puis traiter

Placez une contrainte d’unicité sur l’id de l’enveloppe. Persistez l’enveloppe vérifiée, renvoyez 2xx rapidement, puis traitez-la de manière asynchrone. Si l’ID d’événement existe déjà, acquittez la livraison sans répéter les effets secondaires terminés. Reprenez le travail local en attente ou en échec via votre propre file d’attente de nouvelles tentatives. N’utilisez pas le champ attempt de l’enveloppe comme clé de déduplication ou compteur de nouvelles tentatives de transport.

Récupérer l’état actuel

L’ordre des webhooks n’est pas un historique de ressources faisant autorité. Utilisez resource.type et resource.id pour localiser l’objet, puis récupérez son état actuel avant de mettre à jour votre système. Pour un événement de transfert, appelez GET /v3/transfers/{transferId} :

Refetch transfer

curl --request GET \
  "${API_BASE}/v3/transfers/${TRANSFER_ID}" \
  --header "X-API-Key: ${SWIPELUX_API_KEY}"

Pilotez le statut visible par le client et les actions en aval à partir de la réponse API actuelle. Concevez les effets secondaires pour qu’ils restent sûrs si deux workers traitent des événements liés dans un ordre différent.

Récupérer les livraisons

Utilisez GET /v3/webhooks/portal pour ouvrir les journaux de livraison. Avec webhooks:write, vous pouvez aussi réessayer les livraisons ayant échoué ou démarrer une relecture manuelle. Une clé disposant uniquement de webhooks:read ouvre un portail qui affiche les livraisons, mais qui ne peut ni les réessayer, ni les rejouer, ni révéler les secrets de signature. Chaque relecture doit passer par la même vérification de signature et par la même boîte de réception durable. Pour récupérer après une panne, relisez la fenêtre affectée et récupérez chaque ressource référencée. Les IDs d’événements terminés restent sans effet ; les enregistrements incomplets reprennent de manière asynchrone. Ensuite, vérifiez les livraisons dupliquées et hors ordre en sandbox, puis complétez la checklist Mise en production.

Commencer

Intégrer les clients

Construire les flux monétaires

Mise en production

N’enregistrez que les événements dont vous avez besoin

Modifier les événements d’un endpoint

Vérifier avant l’analyse

Persister, acquitter, puis traiter

Récupérer l’état actuel

Récupérer les livraisons

​N’enregistrez que les événements dont vous avez besoin

​Modifier les événements d’un endpoint

​Vérifier avant l’analyse

​Persister, acquitter, puis traiter

​Récupérer l’état actuel

​Récupérer les livraisons

N’enregistrez que les événements dont vous avez besoin

Modifier les événements d’un endpoint

Vérifier avant l’analyse

Persister, acquitter, puis traiter

Récupérer l’état actuel

Récupérer les livraisons