---
title: "Search Webhook Events"
method: POST
path: "/webhook-events/search"
tags: ["webhookEvents"]
---

# Search Webhook Events

`POST /webhook-events/search`

## Request

- Base URL: `https://api.withpersona.com/api/v1`
- URL: `https://api.withpersona.com/api/v1/webhook-events/search`
- Auth: HTTP bearer

Search for webhook events using a flexible query language.

Webhook events are the individual delivery records for your webhooks — one per event, per
webhook. Use this endpoint to find events (for example, all `failed` deliveries for a given
webhook in a time window) before re-running them.

## Data Freshness

Do not use search for read-after-write flows because the data will not be immediately available
to search. Under normal operating conditions, data is searchable within approximately 1 minute
of creation or modification. Propagation could be delayed during an outage.

## Retention

Webhook events are retained for a limited window. Searches are automatically bounded to that
window, so events older than the retention period are not returned even if requested.

### Searchable Attributes

The following attributes can be used in query predicates:

| Attribute | Description |
|-----------|-------------|
| `updated_at` | Timestamp the event was last updated (i.e. last delivery attempt). Supports `eq`, `gt`, `gte`, `lt`, `lte`. |
| `status` | Delivery status: `pending`, `completed`, `failed`, or `skipped`. |
| `webhook_id` | Webhook token (e.g. `wbh_ABC123`). |
| `event_id` | Event token the webhook event was created from (e.g. `evt_ABC123`). |
| `event_name` | Event name (e.g. `inquiry.completed`). |
| `webhook_event_id` | Webhook event token (e.g. `wbhe_ABC123`). |
| `related_object_ids` | A related object token contained in the event payload. |

All attributes other than `updated_at` support only the `eq` operator.

## Query parameters

- `fields` object
- `page` WebhookEventsSearchPostParametersPage
  - `after` string: Cursor for forward pagination. Use the value from `links.next` in the previous response. Cursors are opaque and must not be constructed by clients.
  - `before` string: Cursor for backward pagination. Use the value from `links.prev` in the previous response. Cursors are opaque and must not be constructed by clients. Cannot be combined with `after`.
  - `size` integer: Number of results to return per page.

## Headers

- `Key-Inflection` 'camel' | 'kebab' | 'snake'
- `Idempotency-Key` string
- `Persona-Version` '2026-09-29' | '2025-12-08' | '2025-10-27' | '2023-01-05' | '2022-09-01' | '2021-08-18' | '2021-07-05' | '2021-02-21' | '2020-05-18': Server API version. More info on versioning can be found [here](https://docs.withpersona.com/versioning).

## Request body

- WebhookEventsSearchWebhookEventsRequest
  - `query` union: Search query using boolean logic (AND/OR/NOT) and comparison operators. Supports predicates with operators: eq (equal), gt (greater than), gte (greater than or equal), lt (less than), lte (less than or equal). Only `updated_at` supports the range operators; all other attributes support only `eq`.
    - WebhookEventsSearchPostRequestBodyContentApplicationJsonSchemaQuery0: Boolean AND clause - combines multiple conditions where ALL must be true. This clause is recursive: each item in the `and` array can be another AND, OR, NOT clause, or a leaf predicate, enabling complex nested queries. Maximum nesting depth: 2 levels, Maximum clauses per AND: 20
      - `and` object[], required
    - WebhookEventsSearchPostRequestBodyContentApplicationJsonSchemaQuery1: Boolean OR clause - combines multiple conditions where AT LEAST ONE must be true. This clause is recursive: each item in the `or` array can be another AND, OR, NOT clause, or a leaf predicate, enabling complex nested queries. Maximum nesting depth: 2 levels, Maximum clauses per OR: 20
      - `or` object[], required
    - WebhookEventsSearchPostRequestBodyContentApplicationJsonSchemaQuery2: Boolean NOT clause - negates a single condition. This clause is recursive: the `not` value can be another AND, OR, NOT clause, or a leaf predicate, enabling complex nested queries. Maximum nesting depth: 2 levels
      - `not` object, required
    - WebhookEventsSearchPostRequestBodyContentApplicationJsonSchemaQuery3: Attribute predicate
      - `attribute` string, required: The attribute name to filter on (e.g., 'updated_at', 'status', 'webhook_id', 'event_name')
      - `operator` string, required: Comparison operator. Possible values: eq (equal), gt (greater than), gte (greater than or equal), lt (less than), lte (less than or equal).
      - `value` union, required: Value to compare against
        - string
        - number, double
        - boolean
  - `sort` WebhookEventsSearchPostRequestBodyContentApplicationJsonSchemaSort: Sort configuration for results
    - `attribute` string, required: The attribute name to sort by. Only `updated_at` is supported.
    - `direction` string, required: Sort direction. Possible values: asc (ascending), desc (descending).
  - `page` WebhookEventsSearchPostRequestBodyContentApplicationJsonSchemaPage: Pagination parameters
    - `after` string: Cursor for forward pagination. Opaque; use the value from `links.next`.
    - `before` string: Cursor for backward pagination. Opaque; use the value from `links.prev`. Cannot be combined with `after`.
    - `size` integer: Number of results to return per page

## Response `200`

This endpoint returns a collection of Webhook Event objects matching the search criteria.

- WebhookEventsSearchWebhookEventsResponse200
  - `data` WebhookEvent[], required: An array of Webhook Events matching the search criteria
    - `type` 'webhook-event'
    - `id` string
    - `attributes` WebhookEventAttributes
      - `status` string: Delivery status of the webhook event. Possible values: pending, completed, failed, skipped.
      - `event-name` string: The name of the event that triggered this webhook delivery.
      - `webhook-id` string: The token of the Webhook this event was delivered to.
      - `event-id` string, nullable: The token of the Event this webhook event was created from, or null if unavailable.
      - `result-code` integer, nullable: HTTP status code returned by the destination endpoint on the most recent delivery attempt, or null if no attempt has been made yet.
      - `attempts-made` integer: Number of delivery attempts made so far.
      - `last-attempted-at` string, date-time, nullable: Timestamp of the most recent delivery attempt, or null if no attempt has been made yet.
      - `created-at` string, date-time
      - `updated-at` string, date-time
  - `links` WebhookEventsSearchPostResponsesContentApplicationJsonSchemaLinks, required
    - `prev` string, nullable, required: URL pointing to the previous page of data, or null if on the first page. Must be used with a POST request and the original request body.
    - `next` string, nullable, required: URL pointing to the next page of data, or null if on the last page. Must be used with a POST request and the original request body.

## Other responses

- `400`: The request was unacceptable, often due to invalid parameters.
- `401`: An invalid API key was provided.
- `403`: The given API key doesn’t have permissions to perform the request or a quota has been exceeded.
- `409`: The request conflicts with another request, often due to attempting to create a duplicate resource.
- `422`: The request modifies the resource in an unacceptable way, often due to an invalid action or parameter.
- `429`: Your organization’s rate limit has been exceeded. We recommend an exponential backoff on requests.

---

[API](https://skmtc.dev/withpersona/apis/withpersona-7.md) - [All operations](https://skmtc.dev/withpersona/apis/withpersona-7/llms.txt) - [OpenAPI document](https://skmtc.dev/withpersona/apis/withpersona-7/revisions/904c4b28844f?raw)