> ## Documentation Index
> Fetch the complete documentation index at: https://bobprince-78964c2b.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<ParamField path="id" type="string" required>
  The endpoint ID.
</ParamField>

<ParamField query="status" type="string">
  Filter by event status. One of: `received`, `delivered`, `failed`, `dead_letter`.
</ParamField>

<ParamField query="from" type="string">
  Return only events received at or after this ISO 8601 timestamp. Example: `2024-05-01T00:00:00Z`.
</ParamField>

<ParamField query="q" type="string">
  Search within event payload bodies. Returns events whose body contains this string.
</ParamField>

<ParamField query="page" type="number" default="1">
  Page number for pagination.
</ParamField>

<ParamField query="limit" type="number" default="50">
  Number of results per page.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://hookdrop.dev/api/endpoints/ep_01hx9k2z3mq8p4j6n7r5st0vwu/events?status=failed&page=1&limit=20" \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
  ```
</CodeGroup>

```bash cURL with search theme={null}
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**

```json theme={null}
{
  "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.

<ParamField path="id" type="string" required>
  The endpoint ID.
</ParamField>

<ParamField path="eventId" type="string" required>
  The event ID.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl https://hookdrop.dev/api/endpoints/ep_01hx9k2z3mq8p4j6n7r5st0vwu/events/evt_01hx9n4z5os0r6l8p9t7uv2wxy \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
  ```
</CodeGroup>

**Response**

<ResponseField name="id" type="string">
  Unique event identifier.
</ResponseField>

<ResponseField name="status" type="string">
  Current delivery status: `received`, `delivered`, `failed`, or `dead_letter`.
</ResponseField>

<ResponseField name="method" type="string">
  HTTP method of the original incoming request (e.g. `POST`).
</ResponseField>

<ResponseField name="headers" type="object">
  All HTTP headers from the original incoming request.
</ResponseField>

<ResponseField name="body" type="object">
  The parsed JSON payload of the incoming request.
</ResponseField>

<ResponseField name="received_at" type="string">
  ISO 8601 timestamp of when Hookdrop captured the event.
</ResponseField>

```json theme={null}
{
  "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.

<ParamField path="id" type="string" required>
  The endpoint ID.
</ParamField>

<ParamField path="eventId" type="string" required>
  The event ID to replay.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://hookdrop.dev/api/endpoints/ep_01hx9k2z3mq8p4j6n7r5st0vwu/events/evt_01hx9n4z5os0r6l8p9t7uv2wxy/replay \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
  ```
</CodeGroup>

**Response**

```json theme={null}
{
  "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.

<ParamField path="id" type="string" required>
  The endpoint ID.
</ParamField>

<ParamField path="eventId" type="string" required>
  The event ID.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl https://hookdrop.dev/api/endpoints/ep_01hx9k2z3mq8p4j6n7r5st0vwu/events/evt_01hx9n4z5os0r6l8p9t7uv2wxy/deliveries \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
  ```
</CodeGroup>

**Response**

<ResponseField name="id" type="string">
  Unique identifier for this delivery attempt.
</ResponseField>

<ResponseField name="attempt" type="number">
  Which attempt this was (1-indexed).
</ResponseField>

<ResponseField name="response_code" type="number">
  HTTP status code returned by your destination server.
</ResponseField>

<ResponseField name="response_body" type="string">
  Raw response body returned by your destination server.
</ResponseField>

<ResponseField name="attempted_at" type="string">
  ISO 8601 timestamp of when this attempt was made.
</ResponseField>

```json theme={null}
[
  {
    "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"
  }
]
```