Notifications

Recevoir un appel signé (webhook) dès qu'une ressource que l'application a le droit de lire change, au lieu d'interroger l'API en boucle. Chaque application a UN point de réception (endpoint), commun à toutes les organisations qui l'ont connectée ; l'organisation de chaque événement est dans son corps. Le corps est mince (type, organisation, site, identifiant de la ressource) et ne porte aucune donnée personnelle : relisez la ressource sur l'API avec vos droits du moment. Toutes les routes de ce domaine exigent le droit webhooks ; recevoir un type exige en plus le droit de lecture de sa ressource.

Lister les livraisons

GET/api/partner/v1/webhooks/deliveries#

webhooks

Rend les livraisons de la connexion du jeton (cette organisation, cette application, cette autorisation), pings compris, triées par date de dernier changement puis identifiant, de la plus ancienne à la plus récente. Après une déconnexion puis une reconnexion de l'organisation, les livraisons de l'ancienne connexion ne sont plus listées. Les livraisons terminées (DELIVERED, DEAD, MUTED, CANCELLED) sont supprimées 30 jours après leur production. Le corps envoyé n'est pas rendu ; data le résume.

Paramètres

statusrequête · enum	Ne garder que les livraisons dans cet état (casse indifférente).
updated_sincerequête · date-time	Ne garder que les livraisons changées à cet instant ou après.
cursorrequête · string	Curseur opaque rendu par la page précédente (`nextCursor`).
limitrequête · integer	Taille de la page. Au-delà de 200, ramené à 200. Défaut : `50`

Réponse

200Une page de livraisons.

Champs de la réponse (2)

itemsWebhookDelivery[]
iduuid	Identifiant de la livraison, égal à l'`id` du corps envoyé et à l'en-tête `Treats-Event-Id`.
typeenum	Type de l'événement. `appointment.createdappointment.updatedappointment.cancelledappointment.no_showappointment.completedpatient.checked_inclient.createdpatient.createdpatient.deceasedconsultation.startedconsultation.validatedinvoice.issuedinvoice.paidpayment.recordedcredit_note.issuedprescription.signedlab.result.receivedping`
occurredAtdate-time	Instant où le fait s'est produit dans Treats.
siteIduuid	Site de l'événement (`null` pour un ping ou un événement sans site). peut être null
dataobject	La ressource désignée.
objectenum	Nature de la ressource. `appointmentclientpatientconsultationinvoicepaymentcredit_noteprescriptionlab_resultping`
iduuid	Identifiant de la ressource. `null` pour un ping. peut être null
publicIdstring	Identifiant public (`apt_…`, `cli_…`, `pat_…`, `cns_…`) quand la ressource en a un et qu'il est connu. peut être null
statusenum	`PENDING` : en file. `SENDING` : envoi en cours. `DELIVERED` : votre endpoint a répondu 2xx. `FAILED` : échec, nouvelle tentative prévue à `nextAttemptAt`. `DEAD` : six tentatives en échec (ou ping en échec), plus de reprise automatique. `MUTED` : organisation de test et application de production, rien n'est envoyé. `CANCELLED` : rien n'est envoyé, `lastError` dit pourquoi (droit, site ou endpoint retiré entre-temps, application de recette face à une organisation réelle…). `PENDINGSENDINGDELIVEREDFAILEDDEADMUTEDCANCELLED`
attemptsinteger	Tentatives comptées depuis la production ou le dernier rejeu (remis à 0 par un rejeu).
nextAttemptAtdate-time	Prochaine tentative prévue. Renseigné seulement pour `PENDING` et `FAILED`. peut être null
lastAttemptAtdate-time	Dernière requête envoyée à l'endpoint. peut être null
lastStatusCodeinteger	Code HTTP de la dernière réponse reçue. `null` si aucune réponse n'est arrivée (délai dépassé, connexion impossible, adresse refusée). peut être null
lastErrorstring	Dernière erreur, en français : `HTTP 503`, `Délai dépassé (10 s)`, `Connexion impossible : …`, `WEBHOOK_URL_FORBIDDEN : …`, ou une raison d'annulation préfixée par son code (`GRANT_REVOKED : …`, `SCOPE_WITHDRAWN : …`, `SITE_NOT_COVERED : …`, `TYPE_UNSUBSCRIBED : …`, `ORGANIZATION_MUTED : …`, `SANDBOX_ORG_LIVE : …`…). `null` si tout s'est bien passé. peut être null
deliveredAtdate-time	Date de la livraison réussie. peut être null
createdAtdate-time	Production de la livraison.
updatedAtdate-time	Dernier changement de la livraison (clé du tri et de `updated_since`).
nextCursorstring	Curseur opaque de la page suivante, à repasser tel quel dans `cursor`. `null` : dernière page. peut être null

Erreurs propres à cette opération

400 INVALID_FIELD

status hors de la liste, updated_since illisible, limit non entier ou inférieur à 1, curseur illisible (un détail par paramètre).

Et les erreurs communes à toutes les opérations : erreurs et limites.

Rejouer une livraison

POST/api/partner/v1/webhooks/deliveries/{id}/replay#

webhooksIdempotency-Key

Remet une livraison de la connexion du jeton en file, quel que soit son état (sauf pendant un envoi) : elle repart dans les secondes qui suivent, avec le même identifiant et le même corps, et ses tentatives repartent de zéro (six tentatives de nouveau, en-tête Treats-Attempt à partir de 1). Les droits, le site, l'abonnement et l'endpoint sont revérifiés à l'envoi : une livraison dont la cause d'annulation demeure est de nouveau annulée. Ne marche que pour une livraison encore conservée (30 jours après sa production une fois terminée).

Paramètres

idchemin · uuidrequis	Identifiant de la livraison (`id` de `GET /webhooks/deliveries`, égal à `Treats-Event-Id`).
Idempotency-Keyen-tête · stringrequis	Clé unique de l'envoi (un UUID). Le même envoi répété avec la même clé n'est appliqué qu'une fois pendant 24 h.

Réponse

202Livraison remise en file : `status` `PENDING`, `attempts` 0.

Champs de la réponse (14)

iduuid	Identifiant de la livraison, égal à l'`id` du corps envoyé et à l'en-tête `Treats-Event-Id`.
typeenum	Type de l'événement. `appointment.createdappointment.updatedappointment.cancelledappointment.no_showappointment.completedpatient.checked_inclient.createdpatient.createdpatient.deceasedconsultation.startedconsultation.validatedinvoice.issuedinvoice.paidpayment.recordedcredit_note.issuedprescription.signedlab.result.receivedping`
occurredAtdate-time	Instant où le fait s'est produit dans Treats.
siteIduuid	Site de l'événement (`null` pour un ping ou un événement sans site). peut être null
dataobject	La ressource désignée.
objectenum	Nature de la ressource. `appointmentclientpatientconsultationinvoicepaymentcredit_noteprescriptionlab_resultping`
iduuid	Identifiant de la ressource. `null` pour un ping. peut être null
publicIdstring	Identifiant public (`apt_…`, `cli_…`, `pat_…`, `cns_…`) quand la ressource en a un et qu'il est connu. peut être null
statusenum	`PENDING` : en file. `SENDING` : envoi en cours. `DELIVERED` : votre endpoint a répondu 2xx. `FAILED` : échec, nouvelle tentative prévue à `nextAttemptAt`. `DEAD` : six tentatives en échec (ou ping en échec), plus de reprise automatique. `MUTED` : organisation de test et application de production, rien n'est envoyé. `CANCELLED` : rien n'est envoyé, `lastError` dit pourquoi (droit, site ou endpoint retiré entre-temps, application de recette face à une organisation réelle…). `PENDINGSENDINGDELIVEREDFAILEDDEADMUTEDCANCELLED`
attemptsinteger	Tentatives comptées depuis la production ou le dernier rejeu (remis à 0 par un rejeu).
nextAttemptAtdate-time	Prochaine tentative prévue. Renseigné seulement pour `PENDING` et `FAILED`. peut être null
lastAttemptAtdate-time	Dernière requête envoyée à l'endpoint. peut être null
lastStatusCodeinteger	Code HTTP de la dernière réponse reçue. `null` si aucune réponse n'est arrivée (délai dépassé, connexion impossible, adresse refusée). peut être null
lastErrorstring	Dernière erreur, en français : `HTTP 503`, `Délai dépassé (10 s)`, `Connexion impossible : …`, `WEBHOOK_URL_FORBIDDEN : …`, ou une raison d'annulation préfixée par son code (`GRANT_REVOKED : …`, `SCOPE_WITHDRAWN : …`, `SITE_NOT_COVERED : …`, `TYPE_UNSUBSCRIBED : …`, `ORGANIZATION_MUTED : …`, `SANDBOX_ORG_LIVE : …`…). `null` si tout s'est bien passé. peut être null
deliveredAtdate-time	Date de la livraison réussie. peut être null
createdAtdate-time	Production de la livraison.
updatedAtdate-time	Dernier changement de la livraison (clé du tri et de `updated_since`).

Erreurs propres à cette opération

404 WEBHOOK_DELIVERY_NOT_FOUND	Aucune livraison de cet identifiant pour la connexion du jeton (autre organisation, autre application, ancienne connexion, ou livraison supprimée).
409 WEBHOOK_DELIVERY_IN_PROGRESS	La livraison est en cours d'envoi : réessayer dans un instant.

Et les erreurs communes à toutes les opérations : erreurs et limites.

Lire l'endpoint de l'application

GET/api/partner/v1/webhooks/endpoint#

webhooks

Rend l'endpoint de l'application : adresse, types abonnés, état (actif ou désactivé après des échecs), série d'échecs en cours et fin de recouvrement d'une rotation. L'endpoint appartient à l'application, pas à l'organisation : tout jeton de l'application qui porte webhooks lit le même. Le secret n'est jamais rendu ici.

Réponse

200L'endpoint.

Champs de la réponse (10)

iduuid	Identifiant de l'endpoint.
urlstring	Adresse HTTPS qui reçoit les événements.
typesstring[]	Types d'événement abonnés, dans l'ordre de `GET /webhooks/event-types`. Tous les types quand aucun n'a été choisi.
activeboolean	`false` : endpoint désactivé par Treats après trois jours d'échecs continus. Plus rien n'est produit pour lui ; `PUT /webhooks/endpoint` le réactive.
disabledAtdate-time	Date de la désactivation. `null` si l'endpoint est actif. peut être null
disabledReasonstring	Raison de la désactivation, en français (début de la série d'échecs et dernière erreur). `null` si l'endpoint est actif. peut être null
failingSincedate-time	Début de la série d'échecs en cours. Remis à `null` à la première livraison réussie (ping compris) et par `PUT /webhooks/endpoint`. peut être null
previousSecretValidUntildate-time	Après une rotation du secret : fin de la période pendant laquelle l'ancien secret signe encore. `null` hors de cette période. peut être null
createdAtdate-time	Création de l'endpoint.
updatedAtdate-time	Dernière modification (adresse, types, rotation du secret, désactivation).

Erreurs propres à cette opération

404 WEBHOOK_ENDPOINT_NOT_FOUND

Aucun endpoint enregistré : en créer un par PUT /webhooks/endpoint.

Et les erreurs communes à toutes les opérations : erreurs et limites.

Créer ou modifier l'endpoint de l'application

PUT/api/partner/v1/webhooks/endpoint#

webhooks

Crée l'endpoint de l'application (201, avec le secret de signature rendu une seule fois) ou modifie celui qui existe (200, sans secret). Une modification remplace l'adresse et les types, ne touche pas au secret (voir POST /webhooks/endpoint/rotate-secret), réactive un endpoint désactivé et remet à zéro sa série d'échecs. L'adresse doit être en https://, sans identifiants ni fragment, 2 048 caractères au plus, et chacune des adresses IP vers lesquelles son nom se résout doit être publique (adresses privées, locales, réservées et de documentation refusées). Elle est revérifiée avant chaque envoi.

Pas d'Idempotency-Key (PUT). Deux premières créations simultanées donnent un seul 201 avec secret ; l'autre rend 200 sans secret. L'endpoint vaut pour toutes les organisations connectées ; il ne reçoit que les événements produits après son enregistrement.

Corps de la requête application/json

urlstringrequis	Adresse HTTPS publique qui recevra les `POST`. Le chemin et les paramètres sont libres.
typesstring[]	Types à recevoir (valeurs de `GET /webhooks/event-types`). Absent ou `null` : tous les types, y compris ceux ajoutés plus tard. `["*"]` : tous les types. Liste vide refusée ; `ping` refusé (ce n'est pas un abonnement).

Réponse

200Endpoint modifié : `secret` à null, `created` à false.

Champs de la réponse (3)

endpointWebhookEndpoint	L'endpoint tel qu'il est enregistré.
iduuid	Identifiant de l'endpoint.
urlstring	Adresse HTTPS qui reçoit les événements.
typesstring[]	Types d'événement abonnés, dans l'ordre de `GET /webhooks/event-types`. Tous les types quand aucun n'a été choisi.
activeboolean	`false` : endpoint désactivé par Treats après trois jours d'échecs continus. Plus rien n'est produit pour lui ; `PUT /webhooks/endpoint` le réactive.
disabledAtdate-time	Date de la désactivation. `null` si l'endpoint est actif. peut être null
disabledReasonstring	Raison de la désactivation, en français (début de la série d'échecs et dernière erreur). `null` si l'endpoint est actif. peut être null
failingSincedate-time	Début de la série d'échecs en cours. Remis à `null` à la première livraison réussie (ping compris) et par `PUT /webhooks/endpoint`. peut être null
previousSecretValidUntildate-time	Après une rotation du secret : fin de la période pendant laquelle l'ancien secret signe encore. `null` hors de cette période. peut être null
createdAtdate-time	Création de l'endpoint.
updatedAtdate-time	Dernière modification (adresse, types, rotation du secret, désactivation).
secretstring	Secret de signature (`whsec_…`), rendu UNE seule fois, à la création (201). `null` sur une modification (200). À conserver côté serveur : Treats ne le rend plus jamais. peut être null
createdboolean	`true` : l'endpoint vient d'être créé (201, secret rendu). `false` : endpoint existant modifié (200).

Erreurs propres à cette opération

400 WEBHOOK_URL_INVALID	Adresse illisible, trop longue, sans hôte, autre que `https://`, avec identifiants (`user:pass@`) ou fragment (`#…`).
400 WEBHOOK_URL_FORBIDDEN	L'hôte est local (`localhost`…) ou l'une de ses adresses IP est privée, locale, réservée ou de documentation.
400 WEBHOOK_URL_UNRESOLVABLE	Le nom de l'hôte ne se résout pas.
400 INVALID_FIELD	`url` absent ou vide ; `types` qui n'est pas une liste de textes, liste vide, type inconnu ou `ping` (un détail par erreur).

Et les erreurs communes à toutes les opérations : erreurs et limites.

Changer le secret de signature

POST/api/partner/v1/webhooks/endpoint/rotate-secret#

webhooksIdempotency-Key

Génère un nouveau secret et le rend une seule fois. L'ancien secret signe encore pendant 24 heures : chaque envoi porte alors deux signatures v1, la nouvelle d'abord, ce qui laisse le temps de déployer le nouveau secret sans coupure. Une seconde rotation dans ces 24 heures remplace l'ancien par le secret en place à ce moment : seuls les deux derniers secrets signent. La rotation ne change ni l'adresse, ni les types, et ne réactive pas un endpoint désactivé. Aucun corps n'est lu.

La même Idempotency-Key rejoue la réponse avec secret: null et secretRedacted: true : le secret n'est jamais conservé en clair. Si la réponse a été perdue, refaites une rotation avec une nouvelle clé.

Paramètres

Idempotency-Keyen-tête · stringrequis

Clé unique de l'envoi (un UUID). Le même envoi répété avec la même clé n'est appliqué qu'une fois pendant 24 h.

Réponse

200Le nouveau secret et la fin de validité de l'ancien.

Champs de la réponse (3)

secretstring	Nouveau secret (`whsec_…`), rendu une seule fois. `null` quand la réponse est rejouée par la même `Idempotency-Key` : le secret n'est jamais conservé en clair ; refaites une rotation avec une nouvelle clé si la réponse a été perdue. peut être null
previousSecretValidUntildate-time	L'ancien secret signe encore jusqu'à cet instant (24 heures après la rotation).
secretRedactedboolean	Présent et `true` seulement sur une réponse rejouée par la même `Idempotency-Key` : le secret a été masqué.

Erreurs propres à cette opération

404 WEBHOOK_ENDPOINT_NOT_FOUND

Aucun endpoint enregistré.

Et les erreurs communes à toutes les opérations : erreurs et limites.

Lister les types d'événement

GET/api/partner/v1/webhooks/event-types#

webhooks

Rend les 17 types d'événement auxquels un endpoint peut s'abonner, avec la ressource que chacun désigne et les droits qui permettent de le recevoir. La liste est la même pour toutes les applications : elle ne dit pas ce que votre connexion reçoit (comparez scopes à ceux de GET /me). Une seule page, nextCursor toujours null. Le type ping n'y figure pas : il n'est produit que par POST /webhooks/test.

Réponse

200Les types publiés, dans un ordre fixe.

Champs de la réponse (2)

itemsWebhookEventType[]
typeenum	Nom du type. `appointment.createdappointment.updatedappointment.cancelledappointment.no_showappointment.completedpatient.checked_inclient.createdpatient.createdpatient.deceasedconsultation.startedconsultation.validatedinvoice.issuedinvoice.paidpayment.recordedcredit_note.issuedprescription.signedlab.result.received`
objectenum	Nature de la ressource désignée par `data.object`. `appointmentclientpatientconsultationinvoicepaymentcredit_noteprescriptionlab_result`
scopesstring[]	Droits dont UN suffit, en plus de `webhooks`, pour recevoir ce type (deux pour `lab.result.received` : `consultations:read` ou `lab:write`).
nextCursorstring	Curseur opaque de la page suivante, à repasser tel quel dans `cursor`. `null` : dernière page. peut être null

Envoyer un ping à l'endpoint

POST/api/partner/v1/webhooks/test#

webhooksIdempotency-Key

Envoie tout de suite un événement ping, signé comme les autres, à l'endpoint de l'application, pour l'organisation du jeton, et rend son verdict. Délai total de 5 secondes pour votre endpoint ; la réponse arrive en 7 secondes au plus. Pas de reprise : un échec rend DEAD avec lastStatusCode ou lastError. Aucun corps n'est lu.

Les règles d'envoi s'appliquent : avec une organisation de test, une application de production obtient MUTED (rien n'est envoyé) ; une application de recette n'envoie qu'à une organisation de test, sinon CANCELLED (SANDBOX_ORG_LIVE). Un seul ping à la fois par application. La même Idempotency-Key rejoue la première réponse sans renvoyer de ping. Dans un cas extrême (verdict pas encore écrit), le statut rendu est SENDING et le verdict se lit dans GET /webhooks/deliveries.

Paramètres

Idempotency-Keyen-tête · stringrequis

Clé unique de l'envoi (un UUID). Le même envoi répété avec la même clé n'est appliqué qu'une fois pendant 24 h.

Réponse

200La livraison du ping et son verdict (`DELIVERED`, `DEAD`, `MUTED`, `CANCELLED`, exceptionnellement `SENDING`).

Champs de la réponse (14)

iduuid	Identifiant de la livraison, égal à l'`id` du corps envoyé et à l'en-tête `Treats-Event-Id`.
typeenum	Type de l'événement. `appointment.createdappointment.updatedappointment.cancelledappointment.no_showappointment.completedpatient.checked_inclient.createdpatient.createdpatient.deceasedconsultation.startedconsultation.validatedinvoice.issuedinvoice.paidpayment.recordedcredit_note.issuedprescription.signedlab.result.receivedping`
occurredAtdate-time	Instant où le fait s'est produit dans Treats.
siteIduuid	Site de l'événement (`null` pour un ping ou un événement sans site). peut être null
dataobject	La ressource désignée.
objectenum	Nature de la ressource. `appointmentclientpatientconsultationinvoicepaymentcredit_noteprescriptionlab_resultping`
iduuid	Identifiant de la ressource. `null` pour un ping. peut être null
publicIdstring	Identifiant public (`apt_…`, `cli_…`, `pat_…`, `cns_…`) quand la ressource en a un et qu'il est connu. peut être null
statusenum	`PENDING` : en file. `SENDING` : envoi en cours. `DELIVERED` : votre endpoint a répondu 2xx. `FAILED` : échec, nouvelle tentative prévue à `nextAttemptAt`. `DEAD` : six tentatives en échec (ou ping en échec), plus de reprise automatique. `MUTED` : organisation de test et application de production, rien n'est envoyé. `CANCELLED` : rien n'est envoyé, `lastError` dit pourquoi (droit, site ou endpoint retiré entre-temps, application de recette face à une organisation réelle…). `PENDINGSENDINGDELIVEREDFAILEDDEADMUTEDCANCELLED`
attemptsinteger	Tentatives comptées depuis la production ou le dernier rejeu (remis à 0 par un rejeu).
nextAttemptAtdate-time	Prochaine tentative prévue. Renseigné seulement pour `PENDING` et `FAILED`. peut être null
lastAttemptAtdate-time	Dernière requête envoyée à l'endpoint. peut être null
lastStatusCodeinteger	Code HTTP de la dernière réponse reçue. `null` si aucune réponse n'est arrivée (délai dépassé, connexion impossible, adresse refusée). peut être null
lastErrorstring	Dernière erreur, en français : `HTTP 503`, `Délai dépassé (10 s)`, `Connexion impossible : …`, `WEBHOOK_URL_FORBIDDEN : …`, ou une raison d'annulation préfixée par son code (`GRANT_REVOKED : …`, `SCOPE_WITHDRAWN : …`, `SITE_NOT_COVERED : …`, `TYPE_UNSUBSCRIBED : …`, `ORGANIZATION_MUTED : …`, `SANDBOX_ORG_LIVE : …`…). `null` si tout s'est bien passé. peut être null
deliveredAtdate-time	Date de la livraison réussie. peut être null
createdAtdate-time	Production de la livraison.
updatedAtdate-time	Dernier changement de la livraison (clé du tri et de `updated_since`).

Erreurs propres à cette opération

404 WEBHOOK_ENDPOINT_NOT_FOUND	Aucun endpoint enregistré.
409 WEBHOOK_ENDPOINT_DISABLED	Endpoint désactivé après des échecs continus : le réactiver par `PUT /webhooks/endpoint`.
503 WEBHOOK_TEST_IN_PROGRESS	Un ping de l'application est déjà en cours. En-tête `Retry-After: 5`. Rien n'est écrit : réessayer avec la même `Idempotency-Key`.
503 WEBHOOK_TEST_BUSY	Trop de pings en cours chez Treats. En-tête `Retry-After: 5`. Rien n'est écrit : réessayer avec la même `Idempotency-Key`.

Et les erreurs communes à toutes les opérations : erreurs et limites.

Notifications envoyées :ping