Vérifié le 2026-11-11 · Version API 2026-11-09 · Lire le Markdown
Webhooks client
Livraison d'événements sortants pour votre espace de travail. Enregistrez un point de terminaison HTTPS, vérifiez le secret de signature à usage unique et recevez des événements signés avec des tentatives bornées.
Enregistrer un point de terminaison
curl -s -X POST -H "Authorization: Bearer $PUBLISHER_KEY" \
-H "Idempotency-Key: $(uuidgen)" -H "Content-Type: application/json" \
$BASE/webhooks -d '{"url": "https://example.com/hooks/autoposted"}'
- Le secret de signature (
whsec_…) est retourné une seule fois : dans la première réponse de création réussie. Stockez-le ; un rejeu idempotent de la même création renvoie le point de terminaison sans le secret, et il ne peut plus être affiché. - Les destinations doivent être en HTTPS, résolubles publiquement et exemptes d'identifiants intégrés. Les requêtes vers des adresses privées, loopback, link-local (y compris les métadonnées cloud), unique-local et multicast sont refusées avant toute connexion, et les redirections ne sont jamais suivies.
- L'enregistrement met en file un événement
webhook.verificationciblé pour ce point de terminaison, indépendamment de son filtreeventTypes. Les événements ordinaires ne circulent qu'après que votre point de terminaison répond à la vérification avec un 2xx.
Vérifier les livraisons
Chaque requête porte :
| En-tête | Signification |
|---|---|
x-publisher-event-id | ID d'événement stable : identique entre tentatives et rejeux |
x-publisher-event-type | Type d'événement, ex. post.published |
x-publisher-timestamp | Secondes Unix |
x-publisher-signature | t=<ts>,v1=<hex> |
La signature est un HMAC-SHA256 sur ${t}.${event_id}.${raw_body} avec votre
secret de signature. Vérifiez avec une tolérance de ±300 secondes et rejetez les rejeux
hors de cette fenêtre. Exemple Node :
import { createHmac, timingSafeEqual } from 'node:crypto';
function verify(secret, headers, rawBody) {
const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(headers['x-publisher-signature']);
if (!m) return false;
const [t, v1] = [Number(m[1]), m[2]];
if (Math.abs(Date.now() / 1000 - t) > 300) return false;
const expected = createHmac('sha256', secret)
.update(`${t}.${headers['x-publisher-event-id']}.${rawBody}`)
.digest('hex');
return timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}
Vérifiez toujours sur le corps de requête brut avant de l'analyser.
Enveloppe d'événement
{
"id": "0192d0d0-0000-7000-8000-00000000000f",
"type": "post.published",
"createdAt": "2026-11-09T12:00:01Z",
"apiVersion": "2026-11-09",
"data": { "postId": "…", "deliveryId": "…", "accountId": "…" }
}
Catalogue initial d'événements (extensible ; eventTypes filtre à l'enregistrement) :
webhook.verification: payload de défi ; répondez 2xx pour activer le point de terminaisonpost.published: une destination confirmée avec un reçu natifdelivery.failed: une destination a échoué de façon terminaledelivery.requires_action: consentement/reconnexion/revue tardive requise
Les résultats agrégés de publication (post.partially_published, post.failed) ne sont pas
encore émis ; ils ne sont documentés ici qu'une fois qu'un producteur existe, ne vous
y fiez donc pas. Abonnez-vous aux événements par destination ci-dessus et déduisez l'état du
lot des résultats de livraison de la publication.
Tentatives, rejeu et désactivation
- Tentatives : immédiatement, puis +1m, +5m, +30m, +2h, +8h. Les tentatives réutilisent le même ID d'événement et un corps identique à l'octet près pour que vous puissiez dédupliquer en toute sécurité.
- 2xx = livré. 429/5xx/timeouts sont retentés. Les autres 4xx échouent définitivement pour cet événement (corrigez le point de terminaison, puis rejouez).
- 410 Gone désactive le point de terminaison : aucun autre événement n'y est mis en file.
- Le rejeu autorisé par un opérateur via le service webhook interne interne renvoie un événement avec son ID d'origine. Une tentative en cours avec bail actif n'est jamais interrompue ; le rejeu signale que l'événement est occupé et peut être retenté sous peu.
Notes opérationnelles
- Les diagnostics de livraison ne stockent que des codes de résultat sûrs : jamais votre secret, les signatures, les en-têtes de requête ou les corps de réponse. Les payloads sont en outre assainis : les secrets fournisseur/OAuth et les URL de presign de médias sont retirés avant toute mise en file.
- Les points de terminaison sont limités à l'espace de travail : posséder l'UUID d'un point de terminaison d'un autre espace de travail ne fait rien.
- La livraison est au-moins-une-fois par occurrence d'événement acceptée ; dédupliquez sur
x-publisher-event-id.
Disponibilité des outils développeur
La page Developers liste les clés d'API de l'espace de travail et les points de terminaison webhook indépendamment de la configuration de chiffrement du secret de signature. Créer un webhook requiert une configuration de chiffrement serveur valide ; demandez à l'opérateur du déploiement de résoudre un avertissement de configuration. La gestion des clés d'API reste disponible. Les secrets de signature existants ne sont plus jamais affichés.