Events API

Inspect, search, and replay captured webhook events

Every HTTP request that hits your capture URL is stored as an event. You can list, filter, inspect, and replay events using the endpoints below.

Events have one of four statuses:

Status	Meaning
received	Captured but not yet delivered to any destination
delivered	Successfully delivered to all configured destinations
failed	At least one delivery attempt failed; retries are ongoing
dead_letter	All retry attempts exhausted; delivery did not succeed

---

List events

GET /api/endpoints/:id/events

Returns a paginated list of events captured by an endpoint. Use the query parameters to filter and search.

id · string · required

The endpoint ID.

status · string

Filter by event status. One of: received, delivered, failed, dead_letter.

from · string

Return only events received at or after this ISO 8601 timestamp. Example: 2024-05-01T00:00:00Z.

q · string

Search within event payload bodies. Returns events whose body contains this string.

page · number · default: "1"

Page number for pagination.

limit · number · default: "50"

Number of results per page.

cURL

curl "https://hookdrop.dev/api/endpoints/ep_01hx9k2z3mq8p4j6n7r5st0vwu/events?status=failed&page=1&limit=20" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

cURL with search

curl "https://hookdrop.dev/api/endpoints/ep_01hx9k2z3mq8p4j6n7r5st0vwu/events?q=payment_intent.succeeded&from=2024-05-01T00:00:00Z" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response

{
  "data": [
    {
      "id": "evt_01hx9n4z5os0r6l8p9t7uv2wxy",
      "status": "failed",
      "method": "POST",
      "received_at": "2024-05-12T12:00:00.000Z"
    },
    {
      "id": "evt_01hx9n4z5os0r6l8p9t7uv2wxz",
      "status": "delivered",
      "method": "POST",
      "received_at": "2024-05-12T11:45:00.000Z"
    }
  ],
  "page": 1,
  "limit": 20,
  "total": 2
}

---

Get a single event

GET /api/endpoints/:id/events/:eventId

Returns the full details of a captured event, including its headers, body, and delivery status.

id · string · required

The endpoint ID.

eventId · string · required

The event ID.

cURL

curl https://hookdrop.dev/api/endpoints/ep_01hx9k2z3mq8p4j6n7r5st0vwu/events/evt_01hx9n4z5os0r6l8p9t7uv2wxy \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response

id · string

Unique event identifier.

status · string

Current delivery status: received, delivered, failed, or dead_letter.

method · string

HTTP method of the original incoming request (e.g. POST).

headers · object

All HTTP headers from the original incoming request.

body · object

The parsed JSON payload of the incoming request.

received_at · string

ISO 8601 timestamp of when Hookdrop captured the event.

{
  "id": "evt_01hx9n4z5os0r6l8p9t7uv2wxy",
  "status": "delivered",
  "method": "POST",
  "headers": {
    "content-type": "application/json",
    "stripe-signature": "t=1715515200,v1=abc123...",
    "user-agent": "Stripe/1.0 (+https://stripe.com/docs/webhooks)"
  },
  "body": {
    "id": "evt_1NtLWHKZSdpsDTYrXGYKjhFD",
    "type": "payment_intent.succeeded",
    "data": {
      "object": {
        "id": "pi_3NtLWHKZSdpsDTYr1AbCdEfG",
        "amount": 1500000,
        "currency": "ngn",
        "status": "succeeded"
      }
    }
  },
  "received_at": "2024-05-12T12:00:00.000Z"
}

---

Replay an event

POST /api/endpoints/:id/events/:eventId/replay

Re-enqueues an event for delivery to all currently configured destinations. This is useful for recovering from failed deliveries or testing destination changes.

id · string · required

The endpoint ID.

eventId · string · required

The event ID to replay.

cURL

curl -X POST https://hookdrop.dev/api/endpoints/ep_01hx9k2z3mq8p4j6n7r5st0vwu/events/evt_01hx9n4z5os0r6l8p9t7uv2wxy/replay \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response

{
  "queued": true,
  "event_id": "evt_01hx9n4z5os0r6l8p9t7uv2wxy"
}

---

Get delivery attempts

GET /api/endpoints/:id/events/:eventId/deliveries

Returns all delivery attempts for an event. Use this to debug failures — you can see exactly what response your destination returned on each attempt.

id · string · required

The endpoint ID.

eventId · string · required

The event ID.

cURL

curl https://hookdrop.dev/api/endpoints/ep_01hx9k2z3mq8p4j6n7r5st0vwu/events/evt_01hx9n4z5os0r6l8p9t7uv2wxy/deliveries \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response

id · string

Unique identifier for this delivery attempt.

attempt · number

Which attempt this was (1-indexed).

response_code · number

HTTP status code returned by your destination server.

response_body · string

Raw response body returned by your destination server.

attempted_at · string

ISO 8601 timestamp of when this attempt was made.

[
  {
    "id": "dlv_01hx9p5z6pt1s7m9q0u8vw3xyz",
    "attempt": 1,
    "response_code": 500,
    "response_body": "Internal Server Error",
    "attempted_at": "2024-05-12T12:00:05.000Z"
  },
  {
    "id": "dlv_01hx9p5z6pt1s7m9q0u8vw3xya",
    "attempt": 2,
    "response_code": 200,
    "response_body": "{\"received\": true}",
    "attempted_at": "2024-05-12T12:00:35.000Z"
  }
]