Webhooks
Les webhooks vous permettent de recevoir des notifications, par exemple lorsqu'un Ask est signé ou lorsqu'une commande dispose de nouvelles données.
Les webhooks sont des requêtes HTTP POST envoyées à l'adresse que vous définissez dans votre dashboard. Si le code de retour HTTP de votre serveur n'est pas 2xx, le système réessaiera de délivrer le webhook, jusqu'à 3 tentatives.
{
"event": {
"_tag": "order.request_success",
"createdAt": "2024-09-17T10:21:32.262Z",
"projectId": "a0efdd19-de68-480d-a92f-458ffd98f5c2",
"orderId": "f720e25e-c662-402e-bd64-aa0771aa819f",
"requestId": "de36dc27-ca90-4c10-ba6c-9524b1f9bcdf",
"requestType": "R63"
}
}
Tous les événements partagent les propriétés communes _tag, createdAt et projectId, complétées par des propriétés propres à chaque type.
_tag | Description | Propriétés spécifiques |
|---|---|---|
ask.verified | Fin de la vérification d'un Ask | askId, status |
ask.accepted | Signature d'un Ask | askId |
ask.contract_access_granted | Accès ouvert sur des contrats d'un Ask | askId, contractSeqs |
ask.revoked | Révocation d'un Ask | askId |
proof.accepted | Justificatif de contrat accepté | askId, proofId |
proof.rejected | Justificatif de contrat rejeté | askId, proofId |
order.request_success | Succès d'une requête au sein d'une commande | orderId, requestId, requestType |
order.request_failed | Échec d'une requête au sein d'une commande | orderId, requestId, requestType |
ask.verified signale la fin des vérifications d'un Ask : chaque point de livraison a reçu une réponse de son gestionnaire de réseau. Son status est celui de l'Ask qui en résulte — PENDING_USER_ACTION, et consentCollectionDetails.userUrl accepte alors la signature, ou NOT_VALID, auquel cas le statusText de chaque contrat dit ce qui bloque. Il est envoyé à nouveau si le retrait de contrats change le statut de l'Ask — par exemple de NOT_VALID à PENDING_USER_ACTION une fois les contrats bloquants retirés.
C'est le webhook à écouter quand un Ask porte beaucoup de contrats : au-delà de quelques points de livraison, nous vérifions chacun d'eux en tâche de fond et POST/ask répond avant la fin des vérifications, avec un Ask en CREATED. Voir Le parcours.
Sur un Ask vérifié avant la réponse HTTP — le cas courant — le webhook est redondant avec le corps de la réponse, et vous pouvez l'ignorer : le nombre de contrats à partir duquel nous basculons en tâche de fond est un détail d'implémentation, ne le devinez pas.
ask.accepted signale la signature du mandat, pas l'ouverture de l'accès aux données. La signature est nécessaire pour récupérer les données d'un contrat, mais elle ne suffit pas : après la signature, nous devons encore faire des opérations, souvent asynchrones, avant d'ouvrir l'accès aux données (communiquer avec Enedis, demander à GRDF d'envoyer au titulaire la demande de confirmation par e-mail ou SMS, etc.).
Chez Enedis, l'accès à chaque contrat s'ouvre en général dans les secondes qui suivent la signature, parfois plusieurs minutes plus tard. Une commande passée dès la réception de ask.accepted peut donc être refusée (No PRM was found to have a valid consent for that request.). Attendez ask.contract_access_granted, qui liste les contrats dont l'accès est ouvert, avant de commander leurs données.
Sur un contrat gaz GRDF, le titulaire doit encore confirmer la demande par e-mail ou SMS : le contrat reste en PENDING_DSO_ACTION jusque-là, et son passage en GRANTED envoie ask.contract_access_granted. Voir la confirmation du titulaire.
ask.contract_access_granted
Ce webhook est envoyé quand des contrats d'un Ask passent en GRANTED. Un contrat en GRANTED est un contrat dont vous pouvez désormais récupérer les données. contractSeqs liste leurs index dans le tableau contracts envoyé à POST/ask, à partir de 0. C'est aussi le seq de chaque contrat dans la réponse de GET/ask/{askId}.
{
"event": {
"_tag": "ask.contract_access_granted",
"createdAt": "2026-10-20T09:12:41.118Z",
"projectId": "a0efdd19-de68-480d-a92f-458ffd98f5c2",
"askId": "5b0e3c7e-8f0b-4f7b-9d0a-2f3c1e6a9b41",
"contractSeqs": [0, 1]
}
}
Un même webhook peut lister plusieurs contrats : les contrats Enedis d'un Ask, qui passent en GRANTED ensemble juste après la signature, arrivent en général dans un seul webhook. Un Ask peut aussi recevoir plusieurs webhooks ; chaque contrat ne figure que dans l'un d'eux.
Pour des raisons de sécurité, nous n'incluons dans les webhooks que les identifiants (askId, orderId, requestId, contractSeqs) et le type de requête. Faites les appels d'API habituels pour obtenir le détail des Asks / Orders correspondants.
Les événements order.request_success / order.request_failed sont émis par requête, pas par commande : une commande contenant trois requêtes déclenche trois webhooks, dans l'ordre où les requêtes se terminent. C'est aussi le cas des requêtes synchrones (*_SYNC), dont le résultat est déjà connu à la fin de l'appel HTTP : le webhook est alors redondant pour vous, et vous pouvez l'ignorer en filtrant sur requestType.
Astuce dev — pour tester vos webhooks en local, exposez votre serveur avec ngrok ou localtunnel, puis déclenchez des webhooks à partir d'un Ask de test (header switchgrid-test-env: true sur le POST /ask). Vous recevrez un webhook à la signature du consentement, puis à chaque requête terminée au sein d'une commande.