Discourse webhook payload example (post_created)

Discourse · event: post (post_created) · content type: application/json

This is a representative sample — fake IDs, real structure. To see a payload with your data, point the provider at a capture URL (button below).

Headers

content-type: application/json
x-discourse-instance: https://forum.acme.dev
x-discourse-event-id: 241
x-discourse-event-type: post
x-discourse-event: post_created
x-discourse-event-signature: sha256=441dfc5a4c2adc109ff70f36ce0883cd1773f32e8dad178ebde8a4933344cdc7

Body

{
  "post": {
    "id": 4182,
    "name": "Ada Deveraux",
    "username": "ada",
    "avatar_template": "/user_avatar/forum.acme.dev/ada/{size}/42_2.png",
    "created_at": "2026-08-30T09:41:27.123Z",
    "cooked": "<p>Webhook deliveries stopped after our TLS cert renewal — anyone else?</p>",
    "post_number": 1,
    "post_type": 1,
    "updated_at": "2026-08-30T09:41:27.123Z",
    "reply_count": 0,
    "reply_to_post_number": null,
    "quote_count": 0,
    "incoming_link_count": 0,
    "reads": 0,
    "score": 0,
    "topic_id": 1287,
    "topic_slug": "webhook-deliveries-stopped-after-tls-cert-renewal",
    "topic_title": "Webhook deliveries stopped after TLS cert renewal",
    "category_id": 6,
    "category_slug": "support",
    "display_username": "Ada Deveraux",
    "primary_group_name": null,
    "version": 1,
    "user_title": null,
    "raw": "Webhook deliveries stopped after our TLS cert renewal — anyone else?",
    "moderator": false,
    "admin": false,
    "staff": false,
    "user_id": 87,
    "hidden": false,
    "trust_level": 2,
    "deleted_at": null,
    "user_deleted": false,
    "edit_reason": null,
    "wiki": false,
    "topic_posts_count": 1,
    "topic_filtered_posts_count": 1,
    "topic_archetype": "regular"
  }
}

Things that bite people

• This example's signature actually verifies. X-Discourse-Event-Signature = sha256= + hex HMAC-SHA256 of the raw body (secret here: hookden-discourse-sample-secret) — GitHub's exact wire format under a Discourse header. Paste body + header value into the signature debugger (generic scheme), or set "Generic HMAC" + header x-discourse-event-signature on a capture bin for live ✓/✗ badges. The secret is optional: leave it empty and Discourse sends no signature header at all.
• The body is wrapped in an envelope key named after the event type. A post event arrives as {"post": {…}}, a topic event as {"topic": {…}} — and the test ping is just {"ping": "OK"}. Handlers that parse for a flat object break on the wrapper. The granular event name (post_created vs post_destroyed…) is in the X-Discourse-Event header, the category in X-Discourse-Event-Type, and the source forum in X-Discourse-Instance — route on headers before parsing the body.
• Retry rules, verified from the shipped source (app/jobs/regular/emit_web_hook_event.rb, main branch 2026-08-30): a non-2xx response other than 404/410 is retried up to 4 times at 5ⁿ⁻¹ minutes — 1 min, 5 min, 25 min, ~2 hrs — and only when the retry_web_hook_events site setting is enabled (it's off on some installs: then every failure is a one-shot).
• 404/410 is a silent drop, not a retry. Same source file: those two statuses schedule no retry — the event is simply gone — and the webhook is deactivated (with a staff-log entry) only once the retry budget was already exhausted by earlier failures. A misdeployed route can eat deliveries indefinitely while the admin UI still shows the hook as active.
• The payload is generated by the system user — Discourse's own docs warn it can include staff-only and private content regardless of who triggered the event. Treat the receiving endpoint as fully trusted, use HTTPS, and set the secret. Every delivery (headers, payload, response) is inspectable under Admin → API → Webhooks → Events, with per-event Redeliver and a Ping button; content type is selectable between JSON and application/x-www-form-urlencoded.

Send it yourself

Reproduce this delivery against any endpoint (your handler, a bin, staging):

$ curl -X POST https://your-endpoint.example/hook \
  -H 'content-type: application/json' \
  -H 'x-discourse-instance: https://forum.acme.dev' \
  -H 'x-discourse-event-id: 241' \
  -H 'x-discourse-event-type: post' \
  -H 'x-discourse-event: post_created' \
  -H 'x-discourse-event-signature: sha256=441dfc5a4c2adc109ff70f36ce0883cd1773f32e8dad178ebde8a4933344cdc7' \
 -d '{
  "post": {
    "id": 4182,
    "name": "Ada Deveraux",
    "username": "ada",
    "avatar_template": "/user_avatar/forum.acme.dev/ada/{size}/42_2.png",
    "created_at": "2026-08-30T09:41:27.123Z",
    "cooked": "<p>Webhook deliveries stopped after our TLS cert renewal — anyone else?</p>",
    "post_number": 1,
    "post_type": 1,
    "updated_at": "2026-08-30T09:41:27.123Z",
    "reply_count": 0,
    "reply_to_post_number": null,
    "quote_count": 0,
    "incoming_link_count": 0,
    "reads": 0,
    "score": 0,
    "topic_id": 1287,
    "topic_slug": "webhook-deliveries-stopped-after-tls-cert-renewal",
    "topic_title": "Webhook deliveries stopped after TLS cert renewal",
    "category_id": 6,
    "category_slug": "support",
    "display_username": "Ada Deveraux",
    "primary_group_name": null,
    "version": 1,
    "user_title": null,
    "raw": "Webhook deliveries stopped after our TLS cert renewal — anyone else?",
    "moderator": false,
    "admin": false,
    "staff": false,
    "user_id": 87,
    "hidden": false,
    "trust_level": 2,
    "deleted_at": null,
    "user_deleted": false,
    "edit_reason": null,
    "wiki": false,
    "topic_posts_count": 1,
    "topic_filtered_posts_count": 1,
    "topic_archetype": "regular"
  }
}'

← All payload examples · Signature debugger · Docs