Retrieve a webhook delivery

Private beta: request access to use webhooks. Retrieve one delivery: its status and error, the event body and headers it carried, and a targets entry per subscriber with the run or session it started or why its filter skipped the event. When the delivery resumed waiting runs, one more entry summarizes them.

GET /api/v1/webhooks/deliveries/{deliveryId}

Retrieve a webhook delivery

cURL

curl "https://api.trigger.dev/api/v1/webhooks/deliveries/whd_1234" \
  -H "Authorization: Bearer $TRIGGER_SECRET_KEY"

200

{
  "id": "whd_1234",
  "endpoint": {
    "id": "wh_cm1a2b3c4d5e6f",
    "declaredId": "stripe"
  },
  "status": "pending",
  "externalDeliveryId": "evt_1PqR2s3T4u5V6w",
  "isTest": true,
  "createdAt": "2023-11-07T05:31:56Z",
  "processedAt": "2023-11-07T05:31:56Z",
  "idempotencyKey": "<string>",
  "event": "<unknown>",
  "headers": {},
  "rawBodyHash": "<string>",
  "error": "<string>",
  "filterReason": "<string>",
  "targets": [
    {
      "id": "process-checkout",
      "type": "task",
      "status": "pending",
      "reason": "<string>",
      "error": "<string>",
      "runId": "run_cm1a2b3c4d5e6f",
      "sessionId": "<string>",
      "waiters": {
        "matched": 123,
        "resumed": 123,
        "failed": 123
      }
    }
  ],
  "updatedAt": "2023-11-07T05:31:56Z"
}

Authorizations

Authorization · string · header · required

Use a named environment API key. It starts with tr_dev_sk_, tr_prod_sk_, tr_stg_sk_, etc.

Create a named API key in the API Keys section of your Trigger.dev project dashboard. Choose the narrowest access preset that supports your integration.

Our TypeScript SDK will default to using the value of the TRIGGER_SECRET_KEY environment variable if it is set. If you are using the SDK in a different environment, you can set the key using the configure function.

import { configure } from "@trigger.dev/sdk";

configure({ accessToken: "tr_dev_sk_1234" });

Path Parameters

deliveryId · string · required

The delivery's id, starts with whd_.

Response

200

application/json

Successful request

id · string · required

The delivery's id.

Example:

"whd_1234"

endpoint · object | null · required

The endpoint the delivery arrived on, or null if it has since been removed.

Show child attributes

status · enum<string> · required

pending is waiting to be routed (including after a retryable error), processing is being routed, succeeded reached at least one subscriber or waiting run with nothing failed, failed means a subscriber failed after its retries, filtered means no subscriber's filter took it, and unmatched means runs were waiting on the endpoint but none matched and no subscriber took it.

Available options: pending, processing, succeeded, failed, filtered, unmatched

externalDeliveryId · string · required

The provider's id for the delivery, such as a Stripe event id or GitHub's X-GitHub-Delivery header.

Example:

"evt_1PqR2s3T4u5V6w"

isTest · boolean · required

Whether the request carried an x-trigger-test header, as test sends from the dashboard do.

createdAt · string<date-time> · required

processedAt · string<date-time> | null · required

idempotencyKey · string · required

The key the delivery was deduplicated on.

event · any · required

The verified event body, capped in size.

headers · object | null · required

The request headers, with credentials such as signatures removed.

Show child attributes

rawBodyHash · string | null · required

A hash of the raw request body.

error · string | null · required

For a failed delivery, the error and the subscriber it came from.

filterReason · string | null · required

For a filtered delivery, why no subscriber took it.

targets · object[] · required

One entry per subscriber, plus a waiter entry when the delivery matched waiting runs.

Show child attributes

updatedAt · string<date-time> · required