Revisionato 2026-11-11 · Versione API 2026-11-09 · Leggi Markdown
Webhook del cliente
Consegna di eventi in uscita per il tuo workspace. Registra un endpoint HTTPS, verifica il segreto di firma monouso, e ricevi eventi firmati con ripetizioni limitate.
Registrare un endpoint
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"}'
- Il segreto di firma (
whsec_…) viene restituito una sola volta: nella prima risposta di creazione riuscita. Conservalo; un replay idempotente della stessa creazione restituisce l'endpoint senza il segreto, e non può essere mostrato di nuovo. - Le destinazioni devono essere HTTPS, risolvibili pubblicamente, e prive di credenziali incorporate. Le richieste verso indirizzi privati, loopback, link-local (inclusi i metadati cloud), unique-local e multicast vengono rifiutate prima che qualsiasi connessione venga effettuata, e i redirect non vengono mai seguiti.
- La registrazione accoda un evento
webhook.verificationmirato per quell' endpoint, indipendente dal suo filtroeventTypes. Gli eventi ordinari fluiscono solo dopo che il tuo endpoint risponde alla verifica con 2xx.
Verificare le consegne
Ogni richiesta porta:
| Header | Significato |
|---|---|
x-publisher-event-id | ID evento stabile: identico tra ripetizioni e replay |
x-publisher-event-type | Tipo di evento, es. post.published |
x-publisher-timestamp | Secondi Unix |
x-publisher-signature | t=<ts>,v1=<hex> |
La firma è HMAC-SHA256 su ${t}.${event_id}.${raw_body} usando il tuo
segreto di firma. Verifica con una tolleranza di ±300 secondi e rifiuta i replay fuori
da tale finestra. Esempio 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));
}
Verifica sempre contro il corpo della richiesta grezzo prima di analizzarlo.
Busta dell'evento
{
"id": "0192d0d0-0000-7000-8000-00000000000f",
"type": "post.published",
"createdAt": "2026-11-09T12:00:01Z",
"apiVersion": "2026-11-09",
"data": { "postId": "…", "deliveryId": "…", "accountId": "…" }
}
Catalogo iniziale degli eventi (estendibile; eventTypes filtra alla registrazione):
webhook.verification: payload di challenge; rispondi 2xx per attivare l'endpointpost.published: una destinazione confermata con una ricevuta nativadelivery.failed: una destinazione fallita in modo terminaledelivery.requires_action: richiesto consenso/riconnessione/revisione tardiva
Gli esiti aggregati del post (post.partially_published, post.failed) non vengono
emessi ancora; sono documentati qui solo quando esiste un producer, quindi non
fare affidamento su di essi. Abbonati agli eventi per destinazione sopra e ricava lo
stato del batch dagli esiti di consegna del post.
Ripetizioni, replay e disattivazione
- Tentativi: immediato, poi +1m, +5m, +30m, +2h, +8h. Le ripetizioni riutilizzano lo stesso ID evento e un corpo byte-identico così puoi deduplicare in sicurezza.
- 2xx = consegnato. 429/5xx/timeout vengono ripetuti. Gli altri 4xx falliscono permanentemente per quell' evento (correggi l'endpoint, poi fai replay).
- 410 Gone disattiva l'endpoint: nessun altro evento viene accodato verso di esso.
- Il replay autorizzato dall'operatore attraverso il servizio webhook interno reinvia un evento con il suo ID originale. Un tentativo in corso con lease attiva non viene mai interrotto; il replay riporta che l'evento è occupato e può essere ritentato a breve.
Note operative
- La diagnostica di consegna memorizza solo codici di esito sicuri: mai il tuo segreto, firme, header della richiesta o corpi della risposta. I payload sono inoltre sanificati: i segreti provider/OAuth e gli URL presign dei media vengono rimossi prima che qualsiasi cosa venga accodata.
- Gli endpoint hanno ambito di workspace: possedere l'UUID di un endpoint di un altro workspace non produce alcun effetto.
- La consegna è at-least-once per ogni occorrenza di evento accettata; deduplica su
x-publisher-event-id.
Disponibilità degli strumenti sviluppatore
La pagina Developers elenca le chiavi API del workspace e gli endpoint webhook indipendentemente dalla configurazione di cifratura del segreto di firma. Creare un webhook richiede una configurazione di cifratura del server valida; chiedi all'operatore del deployment di risolvere un avviso di configurazione. La gestione delle chiavi API resta disponibile. I segreti di firma esistenti non vengono mai mostrati di nuovo.