All docs

Webhooks

Tell your own systems when a conversation starts, a message arrives, a status or assignee changes or a deadline is missed. Signed, retried and replayable.

Updated . 4 min read.

A webhook posts a short JSON message to an address you choose the moment something happens in the Desk. Use it to create a ticket in another tool, post to a chat channel or keep a report up to date. Open Desk settings → Webhooks to set one up. Only the owner or an administrator of the workspace can change them.

What you can listen for

Event Sent when
thread.created A new conversation starts.
message.created A customer or an agent writes in a conversation. Private notes and the lines in the timeline are never sent.
thread.status_changed A conversation is opened, set to pending, snoozed, resolved or marked as spam.
thread.assigned A conversation is assigned to someone, or unassigned.
sla.breached A first reply or resolution deadline is missed.

Leave every event unticked to receive all of them. Imported conversations never send anything.

What arrives

json
{
  "id": "6b1f0f0e-2d7c-4f43-9a54-0c6f3bd8f1c1",
  "event": "thread.status_changed",
  "occurred_at": "2026-11-02T10:15:00+00:00",
  "data": {
    "previous_status": "open",
    "thread": {
      "id": "ab12cd34ef56",
      "subject": "Where is my order?",
      "channel": "email",
      "status": "resolved",
      "priority": "normal",
      "assignee": { "id": 12, "name": "Anna Agent" },
      "queue": null,
      "labels": ["Billing"],
      "customer": { "name": "Maria Meyer", "email": "maria@example.com" },
      "url": "https://formspring.io/desk/threads/ab12cd34ef56",
      "created_at": "2026-11-02T09:58:00+00:00"
    }
  }
}

message.created adds a message next to thread, thread.assigned adds previous_assignee_id and sla.breached adds the clock that was missed (first_response or resolution).

Check the signature

Every message carries these headers:

  • X-Formspring-Event - the event name.
  • X-Formspring-Delivery - the message id. It stays the same when a message is sent again, so you can ignore one you already handled.
  • X-Formspring-Signature - t=<unix time>,v1=<signature>. The signature is an HMAC-SHA256 of <unix time>.<raw body> made with your signing secret. Compare it in constant time and refuse messages whose time is more than a few minutes old.
  • X-Formspring-Key-Id - which secret signed it.

The signing secret is shown once, when you add the webhook. Lost it? Choose New secret. The old secret keeps signing next to the new one for 24 hours, so you can switch your receiver without dropping a message; the signature header then carries two v1 values and your receiver accepts either.

When your server is down

Answer with any 2xx status within 15 seconds. Anything else is tried again after 30 seconds, 2 minutes, 10 minutes, 30 minutes, 1 hour and 3 hours, seven tries in all. Redirects are not followed, and addresses that point to private or internal hosts are refused, both when you save and when a message is sent.

The delivery log

Log on a webhook shows the latest messages: when, which event, the answer your server gave, how many tries it took and the error if it failed. The log keeps 30 days. Send again sends the exact same message once more, for example after you fixed your receiver; it appears as its own line marked as sent again.

A workspace can have up to 10 webhooks. Anything you can do here you can also do with the REST API and the MCP tools.