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 or Bulk Mark Delivered to resolve them.

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.

Show 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

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

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

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

{
  "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
}