Webhooks

Ajoutez webhooks à une table pour déclencher des requêtes HTTP POST sortantes lorsque des enregistrements sont créés, mis à jour ou supprimés. Chaque webhook est du sucre syntaxique au-dessus des automatisations — en interne, il se déploie en un déclencheur d'enregistrement plus une action webhook.send. Les noms de webhooks doivent être uniques au sein de la table.

Propriétés des webhooks

Propriété	Description
name	Requis. Identifiant unique du webhook au sein de la table.
url	Requis. URL de destination. Doit être une URL http(s) absolue valide.
events	Requis. Événements d'enregistrement qui déclenchent la livraison : l'un de create, update, delete (au moins un).
enabled	Booléen. Indique si le webhook est actif (par défaut true).
auth	Authentification de la requête sortante (HMAC, clé API ou bearer). Voir ci-dessous.
retry	Politique de réessai pour les livraisons échouées. Voir ci-dessous.
payload	Sélection des champs du payload et options de métadonnées. Voir ci-dessous.

webhooks:
  - name: order_created
    url: https://hooks.example.com/orders
    events: [create]
    enabled: true

Authentification

auth sécurise la requête. Trois types sont pris en charge ; les secrets/clés/jetons prennent en charge les références $env..

Type	Propriétés
hmac	secret (requis), algorithm (sha256 par défaut, ou sha1), header (nom de l'en-tête de signature).
apiKey	key (requis), header (nom de l'en-tête portant la clé).
bearer	token (requis) envoyé en tant que jeton bearer.

auth: { type: hmac, secret: '$env.PARTNER_WEBHOOK_SECRET', algorithm: sha256 }

auth: { type: apiKey, key: '$env.SERVICE_API_KEY', header: X-API-Key }

auth: { type: bearer, token: '$env.API_BEARER_TOKEN' }

Politique de réessai

retry contrôle la façon dont les livraisons échouées sont réessayées.

Propriété	Description
maxAttempts	Nombre de tentatives de réessai après l'échec initial. 0 désactive les réessais. Par défaut 3.
backoff	Stratégie de backoff : exponential ou fixed.
initialDelay	Millisecondes avant le premier réessai (par défaut 1000).
maxDelay	Délai maximal en millisecondes entre les réessais.

retry: { maxAttempts: 5, backoff: exponential, initialDelay: 1000, maxDelay: 300000 }

Sélection du payload

payload façonne les données envoyées. includeFields (liste blanche) et excludeFields (liste noire) sont mutuellement exclusifs, et chaque champ nommé doit exister sur la table (l'id implicite est toujours valide).

Propriété	Description
includeFields	N'inclut que ces champs (liste blanche).
excludeFields	Exclut ces champs (liste noire).
includePreviousValues	Inclut les valeurs précédentes de l'enregistrement lors des événements update.
includeMetadata	Inclut les métadonnées de l'événement dans le payload.

payload: { includeFields: [customer, status, total], includePreviousValues: true }

Exemple complet

webhooks:
  - name: order_lifecycle
    url: https://hooks.example.com/orders
    events: [create, update, delete]
    enabled: true
    auth: { type: hmac, secret: '$env.ORDER_WEBHOOK_SECRET', algorithm: sha256 }
    retry: { maxAttempts: 5, backoff: exponential, initialDelay: 1000, maxDelay: 300000 }
    payload: { excludeFields: [internal_notes], includePreviousValues: true }