Payloads de webhook

Els tipus d'esdeveniment dels webhooks de Feedjolt i les capçaleres que emmarquen cada enviament. Forma del payload, signatura, idempotència i estabilitat.

Cada lliurament de webhook és un POST application/json al teu endpoint. El cos és el payload de l'esdeveniment - no hi ha embolcall; el tipus d'esdeveniment i la marca de temps van en capçaleres HTTP.

Capçaleres

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

Bifurca per X-Feedjolt-Event al teu handler.

Tipus d'esdeveniment

Esdeveniment	Quan
`post.created`	Es crea un nou post en un tauler al qual estàs subscrit.
`post.merged`	Un post es fusiona amb un altre.
`post.moderated`	Un esborrany s'aprova o rebutja.
`status.changed`	Un post canvia d'estat.
`comment.created`	Es publica un nou comentari (públic o intern).
`vote.threshold`	Un post supera un llindar de vots configurat.

Aquests són els tipus d'esdeveniment actualment suportats per l'enum NotificationEventType del backend. Esdeveniments addicionals (edicions de posts, eliminacions, edicions de comentaris, publicacions de changelog) estan al full de ruta - vota'ls.

Forma del payload

El cos és el mateix dict que fem servir internament per renderitzar notificacions. El conjunt exacte de camps varia per tipus d'esdeveniment. Els esquemes viuen a la referència OpenAPI sota la secció de webhooks, ja que comparteixen tipus amb l'API.

Un cos representatiu de status.changed es veu aproximadament com:

{
  "id": "evt_abc123",
  "post": {
    "id": "post_xyz",
    "title": "Add dark mode",
    "url": "https://feedjolt.com/p/acme/posts/post_xyz",
    "board_slug": "feature-requests"
  },
  "from_status": { "name": "Planificat", "color": "#6366F1" },
  "to_status":   { "name": "En curs", "color": "#FB923C" },
  "actor":       { "type": "admin_user", "email": "[email protected]" }
}

Tracta el camp id com a clau d'idempotència - veure Reintents.

Estabilitat de camps

Actualment no versionem els payloads d'esdeveniment. Si necessitem fer un canvi trencador, afegirem un nou tipus d'esdeveniment al costat del vell i migrarem al nostre propi ritme.
Podem afegir camps a payloads existents sense previ avís. Programa defensivament (no fallis davant claus desconegudes).

Truncament

Els cossos llargs (cos de post, cos de comentari) no es trunquen avui; enviem el contingut complet. Si el teu endpoint té límit de mida de petició, deixa'l generós. El timeout de lliurament de 10 segons és la primera fallada més probable.