Événements webhook

L'enveloppe de l'événement

Chaque livraison webhook est une requête HTTP POST avec un corps JSON. Tous les événements partagent la même enveloppe de premier niveau :

{
  "id": "evt_9f2c4b7a1d3e5f60718293a4b5c6d7e8",   // clé d'idempotence
  "type": "order.approved",                        // nom de l'événement
  "apiVersion": "2026-07-01",
  "createdAt": "2026-07-28T14:30:00.000Z",
  "account": {
    "uid": "abc123",
    "companyName": "Acme Home Services"
  },
  "data": { /* instantané de la ressource — voir ci-dessous */ },
  "changes": {                                     // uniquement sur *.approved, *.completed,
    "previous": { "status": "new" },               // *.status_changed, *.rescheduled
    "current": { "status": "approved" }
  }
}

Chaque livraison porte aussi le nom de l'événement dans l'en-tête de requête webhook-event, aux côtés des en-têtes de signature (webhook-id, webhook-timestamp, webhook-signature) décrits dans le guide des webhooks.

Index des événements

Les valeurs de statut dans les charges utiles sont les valeurs brutes stockées (draft, new, read, approved, complete, archived) — voir Statuts des commandes.

Événements de commande — charge utile data

order.created, order.approved, order.completed, order.rescheduled et order.status_changed envoient tous le même instantané de Order dans data :

{
  "id": "req_abc123",                              // ID de la commande
  "status": "approved",                            // voir la référence Statuts des commandes
  "appointmentDateTime": "2026-08-01T13:00:00.000Z",
  "inspectionType": "Buyer Inspection",            // le nom de votre catégorie de service
  "streetAddress": "123 Main St",
  "city": "Springfield",
  "region": "IL",
  "postalCode": "62701",
  "country": "US",
  "timezone": "America/Chicago",
  "contactName": "Jane Buyer",
  "contactEmail": "jane@example.com",
  "contactPhone": "(555) 123-4567",
  "contactType": "client",
  "totalPrice": 450,
  "totalTime": 120,                                // durée en minutes
  "paid": false,
  "agreementSigned": true,
  "assignedInspectors": ["uid1", "uid2"],          // IDs des membres d'équipe assignés
  "requestDateTime": "2026-07-20T09:15:00.000Z",   // quand la commande a été créée
  "approvedDateTime": "2026-07-21T10:00:00.000Z",
  "completedDateTime": "2026-08-01T16:30:00.000Z"
}

Les champs de date sont des chaînes ISO 8601. Tout champ sans valeur est omis de la charge utile plutôt qu'envoyé comme null.

changes par événement de commande

• order.approved — changes.previous.status / changes.current.status (current est toujours "approved")
• order.completed — changes.previous.status / changes.current.status (current est toujours "complete")
• order.status_changed — changes.previous.status / changes.current.status
• order.rescheduled — changes.previous.appointmentDateTime / changes.current.appointmentDateTime (chaînes ISO 8601)
• order.created — pas de champ changes

invoice.paid — charge utile data

Se déclenche la première fois que l'indicateur paid d'une Order devient true. La charge utile data est le même instantané de Order montré ci-dessus — pas un objet facture. Il n'y a pas de champs spécifiques à la facture (pas de numéro de facture, de montant payé ou de mode de paiement) ; utilisez totalPrice et l'indicateur paid: true, ou récupérez les détails de la facture via l'API. Aucun champ changes n'est envoyé.

report.published — charge utile data

Se déclenche quand une Order devient pour la première fois à la fois payée et avec contrat signé — le moment où son Report publié est mis à disposition du client. La charge utile data est l'instantané de Order montré ci-dessus, plus un champ supplémentaire :

{
  "orderId": "req_abc123",   // identique à data.id — la commande à laquelle ce rapport appartient
  "id": "req_abc123",
  "status": "complete"
  // …tous les autres champs de l'instantané de commande
}

Aucun champ changes n'est envoyé. La charge utile n'inclut pas les URL du rapport.

Événements auxquels vous pouvez vous abonner mais qui ne se déclenchent pas encore

L'éditeur de point de terminaison liste aussi order.updated, invoice.created, contact.created et contact.updated. Ces noms d'événements sont réservés et peuvent être sélectionnés, mais aucune activité de compte ne les produit actuellement — les points de terminaison abonnés uniquement à ces événements ne recevront aucune livraison. S'ils sont émis dans le futur, ils utiliseront l'enveloppe standard ; leurs champs data ne sont pas encore définis.

Événements de test — webhook.test

Cliquer sur Test sur un point de terminaison envoie un événement webhook.test :

{
  "id": "evt_test_5f0e…",        // préfixé evt_test_
  "type": "webhook.test",
  "apiVersion": "2026-07-01",
  "createdAt": "2026-07-28T14:30:00.000Z",
  "account": { "uid": "abc123" },
  "data": {
    "message": "This is a test webhook event.",
    "timestamp": "2026-07-28T14:30:00.000Z"
  }
}

Les événements de test ne sont pas signés — ils portent un en-tête X-Webhook-Test: true au lieu des en-têtes de signature. Votre récepteur devrait les accepter sans vérification de signature (ou reconnaître l'en-tête et ignorer la vérification uniquement pour les tests).

Répondre aux livraisons

• Répondez avec n'importe quel statut 2xx dans les 10 secondes pour accuser réception d'une livraison.
• Les réponses 5xx et les délais d'attente dépassés sont considérés comme temporaires — la livraison est retentée.
• Les autres réponses 4xx sont considérées comme permanentes — cette livraison n'est pas retentée.
• Répondre 410 Gone indique à ITB d'arrêter l'envoi : le point de terminaison est désactivé immédiatement.

Les limites des points de terminaison, la désactivation automatique après échecs répétés, l'historique des livraisons et la vérification de signature sont couverts dans le guide des webhooks.

Sur le même sujet

• Webhooks — configurer des points de terminaison, secrets et historique des livraisons
• Connecter des applications à l'API — clés API et applications OAuth comme Zapier
• Intégrations — tout ce qui se trouve dans l'onglet Intégrations
• Statuts des commandes — les valeurs de statut qui apparaissent dans les charges utiles