Delivery Status

Retrieves the 20 most recent delivery receipts for a subscription. This is the troubleshooting endpoint: it tells you whether webhooks are being sent, whether they are being received, and exactly what the external system said back.

Request

GET ~/api/webhook/status/:id

:id is the server-assigned UUID from create, not your webhookId.

Request

curl "https://{host}/{instance}/api/webhook/status/b3ff4f99-1436-4989-96a5-cb43341fc9e4" \
  -H "Authorization: Bearer <access-token>" \
  -H "Accept: application/json"

Response

A JSON array of receipts, most recent first.

200 OK

[
  {
    "subscriptionId": "b3ff4f99-1436-4989-96a5-cb43341fc9e4",
    "hasAuthorizationHeader": true,
    "url": "https://externalsystem.com",
    "response": "Optional Response Information",
    "headers": {
      "transfer-Encoding": "chunked",
      "connection": "keep-alive",
      "x-Request-Id": "837ea952-2c56-4470-aa89-3f996ad1b65c",
      "x-Token-Id": "46054f26-412f-4772-a1d6-48648421fbc3",
      "x-RateLimit-Limit": "30",
      "x-RateLimit-Remaining": "26",
      "cache-Control": "no-cache",
      "content-Type": "text/plain; charset=UTF-8",
      "date": "Fri, 07 Dec 2018 19:54:53 GMT",
      "server": "nginx/1.10.3"
    },
    "status": 500,
    "timeStamp": "2018-12-07T19:54:09.59Z",
    "retryCount": 3,
    "wasReceived": false
  }
]

Field	Type	Description
subscriptionId	string	UUID of the subscription this receipt belongs to.
hasAuthorizationHeader	boolean	Whether an Authorization header was sent. The value is never exposed, only its presence.
url	string	The URL the delivery was attempted against.
response	string	The body your endpoint returned. Often the most useful field here.
headers	object	The response headers your endpoint returned.
status	integer	The HTTP status code your endpoint returned.
timeStamp	string	UTC timestamp of the delivery attempt.
retryCount	integer	How many consecutive failures had occurred at this point.
wasReceived	boolean	Whether the delivery was considered successful — true only for 200 OK.

The secret and the authorizationHeader value are deliberately excluded from receipts.

Reading a Receipt

The example above is a failure: status is 500, wasReceived is false, and retryCount has climbed to 3. Two more and the subscription is taken out of service.

Symptom	Likely cause
No receipts at all	Nothing was ever sent. The subscription is disabled, or its event types match nothing.
status 401 or 403	Your endpoint rejected the caller. Check hasAuthorizationHeader — see below.
hasAuthorizationHeader is false unexpectedly	The header was never stored. Almost always the authroizationHeader typo — see create.
status 404	The url is wrong, or the route moved.
status 500	Your handler threw. response usually carries the detail.
status 0, or receipts absent while events fire	The request never completed — DNS, TLS, firewall or timeout. Check the instance can reach url at all.
wasReceived false with a 2xx that is not 200	Only 200 counts. Return 200, not 201 or 204.
Signature check failing on your side	You are hashing a re-serialized body. See verifying the payload.

note

hasAuthorizationHeader is the fastest typo check

If your endpoint is returning 401 and this field is false on every receipt, the subscription has no stored Authorization value — regardless of what you thought you sent. That's the signature of an authroizationHeader misspelling in the create request. Fix it with update, then re-enable if the subscription was disabled.

Notes

• Only the 20 most recent attempts are retained. On a high-volume subscription the window is short, so investigate promptly.
• Receipts record delivery attempts, not events. An event that matched nothing produces no receipt.
• A subscription disabled by repeated failure stops producing receipts, so the last 20 will be the failures that disabled it.

Related Topics

• Query subscriptions — retryCount and lastResponseAt at a glance
• Update a subscription — fixing and re-enabling
• Webhook payload — what to return, and how to verify
• Webhooks overview