API Webhooks

Liste les notifications webhook du projet au format webhook, de la plus ancienne à la plus récente (50 au plus); GET /api/notifications liste tous les canaux. Le secret de signature n’est jamais renvoyé ici. Exige la capacité project; un justificatif d’identité limité aux rapports est refusé avec 403 forbidden, car la réponse comprend les URL des récepteurs.

Crée un webhook qui reçoit les événements durables du projet sous forme de POST HTTPS signés. L’URL doit être https sur un hôte Internet public : une adresse IP littérale ou chaque réponse DNS actuelle du nom doit être publique (privé, loopback, link-local, CGNAT, IPv6 hors 2000::/3, documentation et autres plages réservées sont refusées avec webhook_url_rejected).

Le port doit être 443 (par défaut) ou 8443, sinon webhook_url_rejected. L’hôte est résolu et vérifié à nouveau avant chaque livraison et la connexion est établie à l’adresse vérifiée exacte, donc une réponse DNS qui change plus tard ne peut pas rediriger les livraisons. event_types liste les types d’événements exacts (screen.online) ou les préfixes finissant par .* (screen.*).

Une organisation compte au plus 50 notifications, tous canaux confondus (webhook_limit_reached). Le serveur génère le secret de signature et ne le renvoie que dans cette réponse et dans rotate-secret; conservez-le. Une nouvelle tentative identique avec la même Idempotency-Key renvoie cette même réponse, secret compris, pendant vingt-quatre heures.

La livraison commence avec le premier événement après notification.created.

Requiert la capacité du projet ; un justificatif en lecture seule est refusé 403 interdit, car la réponse inclut des URL de récepteur.

Modifie l’un des éléments url, event_types, activé et description (une description vide la supprime). Une nouvelle url est vérifiée comme à la création.

Activer un webhook désactivé efface son état d’échec et démarre la livraison à l’événement qui enregistre le changement ; les événements survenus pendant sa désactivation ne sont pas rejoués, et les livraisons encore en attente d’avant la désactivation échouent avec webhook_disabled. Désactiver un webhook échoue ses livraisons en attente avec webhook_disabled.

Ajoute notification.updated. If-Match protège la révision.

Supprime le webhook et ajoute notification.deleted. Ses livraisons en attente sont marquées comme échouées avec webhook_deleted; son journal de livraison n'est plus adressable et expire avec la conservation des événements.

Remplace le secret de signature et renvoie le nouveau; l'ancien secret cesse de signer immédiatement : toute tentative qui signe après la validation de cette opération utilise le nouveau secret, et au plus une tentative par webhook déjà en cours peut encore arriver signée avec l'ancien, donc acceptez les deux brièvement. Ajoute notification.updated avec details.changed [secret].

Une nouvelle tentative exacte avec la même Idempotency-Key retourne le même nouveau secret pendant vingt-quatre heures.

Ajoute un événement de projet notification.test et met en file d'attente une livraison de cet événement pour ce webhook uniquement (aucun autre webhook ne reçoit notification.test). Il fonctionne sur un webhook désactivé, n'est tenté qu'une fois, sans nouvelle tentative, est mesuré comme toute livraison et ne modifie jamais l'état d'échec du webhook. Interrogez le journal des livraisons pour en connaître le résultat.

Le journal de livraison du webhook, événement le plus récent en premier. Une ligne par (webhook, événement) ; les tentatives de nouvelle livraison mettent à jour la ligne et GET .../deliveries/{delivery_id}/attempts liste ses tentatives les plus récentes. Les lignes sont conservées comme les événements (la rétention des événements du plan, au moins la fenêtre de nouvelle tentative de 24 heures). Renvoyez next_cursor dans le paramètre before pour la page suivante.

Les tentatives d’une livraison, les plus récentes en premier, les 20 dernières, conservées avec la ligne de livraison et aussi longtemps. Chacune a son numéro de tentative, sa fin, le statut HTTP du récepteur (null quand aucun n’a répondu), la classe d’erreur (null en cas de succès) et sa durée. Les corps et en-têtes de réponse ne sont jamais conservés. Une livraison enregistrée avant la conservation des tentatives n’en liste aucune.

Une livraison qui n’est pas celle de ce webhook, ou un webhook d’un autre projet, est not_found.