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

# Search Webhook Events by Type, Context, or Delivery Status

> GET /v1/webhooks/events/search — Query webhook events by type, context ID or type, and delivery status. Ideal for operational recovery after an outage.

This endpoint lets you search across all webhook events for your tenant using flexible filter criteria. You can narrow results by the resource the event relates to (its `contextId` and `contextType`), by event type, or by delivery status. It is especially useful for operational recovery — after a service outage or deployment, query for `deliveryStatus=NOT_DELIVERED` to surface every event that needs to be re-processed, then use [Redeliver Events](https://diameterpay.mintlify.site/api-reference/webhooks/redeliver-events.md) or [Bulk Mark Delivered](https://diameterpay.mintlify.site/api-reference/webhooks/bulk-mark-delivered.md) to resolve them.

> [!TIP]
>
> After a service restart or planned maintenance window, query `GET /v1/webhooks/events/search?deliveryStatus=NOT_DELIVERED` to find all events that arrived while your endpoint was unavailable. You can then redeliver or manually process and mark them as delivered.

## Endpoint

```
GET /v1/webhooks/events/search
```

**Required scope:** `webhooks.read`

## Request Headers

| Header | Required | Description |
| - | - | - |
| `Authorization` | Yes | `Bearer {access_token}` |

## Query Parameters

**page** `integer`

Page number to retrieve, starting at `1`. Defaults to `1`.

**limit** `integer`

Number of events per page. Defaults to `20`. Maximum is `100`.

**contextId** `string`

The ID of the resource that generated the event — for example, a payment ID, account ID, or end-user ID. Use this to retrieve all events related to a specific object.

**contextType** `string`

The type of resource the event relates to. Accepted values:

* `PAYMENT`
* `END_USER`
* `COUNTERPARTY`
* `ACCOUNT`

**eventTypes** `array`

One or more event type strings to filter results. When multiple values are provided, events matching any of the specified types are returned.

**deliveryStatus** `string`

Filter by delivery outcome. Accepted values:

* `DELIVERED` — the event was successfully delivered to at least one subscription endpoint.
* `NOT_DELIVERED` — the event has not yet been successfully delivered. Includes events pending retry and events where all retry attempts have failed.

## Response — 200 OK

**data** `array`

Array of webhook event objects.

**Event object fields**

**id** `string`

Unique identifier for this webhook event.

**tenantId** `string`

The tenant this event belongs to.

**eventType** `string`

The event type string, e.g. `PAYMENT_WIRE_OUTBOUND_COMPLETED`.

**contextId** `string`

The ID of the resource that triggered this event.

**contextType** `string`

The resource type: `PAYMENT`, `END_USER`, `COUNTERPARTY`, or `ACCOUNT`.

**payload** `object`

The full event payload as delivered to subscribed endpoints.

**createdAt** `string`

ISO 8601 timestamp of when the event was generated.

**page** `integer`

The current page number.

**limit** `integer`

The number of records per page used for this response.

**total** `integer`

Total number of events matching the applied filters.

## Examples

### Find all undelivered events

```bash theme={null}
curl --request GET \
  --url 'https://api.diameterpay.com/v1/webhooks/events/search?deliveryStatus=NOT_DELIVERED' \
  --header 'Authorization: Bearer {access_token}'
```

### Find all events for a specific payment

```bash theme={null}
curl --request GET \
  --url 'https://api.diameterpay.com/v1/webhooks/events/search?contextId=pay_9f8e7d6c5b4a3210&contextType=PAYMENT' \
  --header 'Authorization: Bearer {access_token}'
```

### Search for failed wire completion events

```bash theme={null}
curl --request GET \
  --url 'https://api.diameterpay.com/v1/webhooks/events/search?eventTypes=PAYMENT_WIRE_OUTBOUND_COMPLETED&eventTypes=PAYMENT_WIRE_OUTBOUND_FAILED&deliveryStatus=NOT_DELIVERED&limit=50' \
  --header 'Authorization: Bearer {access_token}'
```

### Response

```json theme={null}
{
  "data": [
    {
      "id": "evt_a1b2c3d4e5f6789012345678",
      "tenantId": "ten_0987654321fedcba",
      "eventType": "PAYMENT_WIRE_OUTBOUND_COMPLETED",
      "contextId": "pay_9f8e7d6c5b4a3210",
      "contextType": "PAYMENT",
      "payload": {
        "paymentId": "pay_9f8e7d6c5b4a3210",
        "status": "COMPLETED",
        "amount": 150000,
        "currency": "USD",
        "completedAt": "2024-06-10T15:32:00.000Z"
      },
      "createdAt": "2024-06-10T15:32:01.000Z"
    }
  ],
  "page": 1,
  "limit": 20,
  "total": 1
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.