Webhooks per a devs: capçaleres, firma i fallades

Referencia tecnica dels webhooks de Feedjolt: que entreguem, les capcaleres i el temps limit, verificar signatures, ser idempotent i gestionar errors d'entrega.

Quan passa alguna cosa a Feedjolt, fem POST del teu payload al teu endpoint. Aquesta secció és la referència orientada a enginyeria.

Per configurar un webhook (UI, triar esdeveniments, aconseguir un secret), veure Integracions -> Webhooks.

Requisits de l'URL de l'endpoint

Cada URL ha de ser una adreça http o https vàlida que resolgui a una IP pública enrutable globalment. Feedjolt rebutja URLs que apuntin a xarxes privades, loopback, rangs link-local (inclosos metadades cloud a 169.254.169.254) o adreces multicast — en crear/actualitzar i de nou a cada lliurament (amb la connexió TCP fixada a la IP resolta per bloquejar DNS rebinding).

Producció: usa una URL HTTPS accessible des d'internet.
Dev local: amb l'API en DEBUG=true, s'ometen les comprovacions SSRF i funcionen receptors http://localhost:….
Sense redireccions: els lliuraments no segueixen redirects HTTP.

Si el desament falla amb "URL resolves to a private or reserved address", el hostname no és accessible des dels servidors de Feedjolt.

Què lliurem

POST application/json amb tres capçaleres rellevants:

Content-Type: application/json
X-Feedjolt-Signature: sha256=<hex>
X-Feedjolt-Event: status.changed
X-Feedjolt-Timestamp: 2026-04-30T12:34:56.789012+00:00

El cos és el payload de l'esdeveniment - veure Payloads.

Què esperem de tornada

2xx - lliurament correcte. Registrat com a èxit.
Qualsevol altra cosa - registrat com a fallada. Sense reintent automàtic avui. Un admin de l'espai pot replayar manualment des del panell.
Timeout de 10 segons - respon ràpid, posa el treball pesat a la cua.

Tres coses que has de fer

Verifica la firma. Veure Firma. Sense verificació, qualsevol a internet pot falsificar esdeveniments.
Sigues idempotent. El replay manual envia el mateix esdeveniment de nou; fes servir l'id del payload com a clau de deduplicació.
Respon ràpid. Retorna 200 en menys de 10 segons. Posa qualsevol treball llarg a la cua.

Tres coses per saber

Els logs són la teva alarma. No hi ha auto-desactivació d'endpoints fallits avui. Vigila Configuració -> Webhooks -> Lliuraments o l'equivalent de l'API.
L'ordre no es garanteix. Fes servir marques de temps del payload per ignorar esdeveniments vells.
Poden aparèixer nous tipus d'esdeveniment segons els enviem. Si t'has subscrit a una allow-list petita, controles el teu radi d'explosió; si t'has subscrit a tots els esdeveniments, espera canvis.

Què hi ha on

Payloads - tipus d'esdeveniment actuals, com es veuen els seus cossos.
Firma - codi de verificació en Node, Python, Ruby, Go.
Reintents - com es gestionen les fallades avui, què ve.

Webhooks per a desenvolupadors