# Webhook notifications

Notifications of events, sent to webhooks

Base URL: `https://api.cv-transformer.com/v1`. Endpoints: `GET /webhook_notifications`. Authenticate with the header `Authorization: Bearer YOUR_API_KEY` (see [authentication](https://www.cv-transformer.com/en-GB/api-reference/authentication.md)).

## The webhook notification object

| Attribute | Type | Description |
| --- | --- | --- |
| `id` | `uuid` | Unique identifier. |
| `webhook_id` | `uuid` | Identifier of the related webhook. References [`webhooks.id`](https://www.cv-transformer.com/en-GB/api-reference/webhooks.md). |
| `created_at` | `timestamp with time zone` | Creation timestamp. |
| `updated_at` | `timestamp with time zone` | Last modification timestamp. |
| `created_on` | `date` | Date on which the notification was created. |
| `event_type` | `WebhookEvent` | Event this notification is for. |
| `next_attempt_at` | `timestamp with time zone` | When the next delivery attempt is due, or the end of the claim of the attempt in progress. |
| `payload` | `jsonb` | JSON payload that is sent along with this notification: the object before (`old`, null for `.created` events) and after (`new`) the change. Member events add the user's `name` and `email` to both under `user_profiles`. |
| `response` | `text \| null` | Response body or error of the last delivery attempt, cut to 2,000 characters. |
| `status` | `WebhookNotificationStatus` | Status of the notification. |
| `tries` | `integer` | Number of delivery attempts. |

```json
{
  "id": "00000000-0000-0000-0000-000000000000",
  "webhook_id": "00000000-0000-0000-0000-000000000000",
  "created_at": "2026-01-01T12:00:00+00:00",
  "updated_at": "2026-01-01T12:00:00+00:00",
  "created_on": "2026-01-01",
  "event_type": "candidates.created",
  "next_attempt_at": "2026-01-01T12:00:00+00:00",
  "payload": {},
  "response": "",
  "status": "sent",
  "tries": 0
}
```

### Types

```typescript
type WebhookNotificationStatus = "error" | "pending" | "sent";

type WebhookEvent = 
  | "candidates.created"
  | "candidates.updated"
  | "layouts.created"
  | "layouts.updated"
  | "members.created"
  | "members.updated";
```

### Related resources

Embed related resources with the [`select` parameter](https://www.cv-transformer.com/en-GB/api-reference/selecting.md), for example `select=*,webhooks(*)`. Resources related through more than one column need the column as a hint, like `table!column(*)`.

| Embed | Type | Description |
| --- | --- | --- |
| `webhooks(*)` | `object \| null` | The [webhook](https://www.cv-transformer.com/en-GB/api-reference/webhooks.md) referenced by `webhook_id`. |

## List webhook notifications

`GET /v1/webhook_notifications` · requires the `webhooks:read` scope

Filter on any attribute with `column=operator.value` (see [filtering](https://www.cv-transformer.com/en-GB/api-reference/filtering.md)). Choose columns and embed related resources with `select` (see [selecting](https://www.cv-transformer.com/en-GB/api-reference/selecting.md)), and sort and paginate with `order`, `limit` and `offset` (see [sorting and pagination](https://www.cv-transformer.com/en-GB/api-reference/sorting-pagination.md)).

```bash
curl "https://api.cv-transformer.com/v1/webhook_notifications?limit=10&select=*" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Responses:

- `200`: A list of webhook notifications with the selected columns. The `Content-Range` header holds the range returned and the total count, like `0-9/42`.
- `206`: Partial Content
- `400`: The request is malformed, for example an unknown column or an invalid filter.
- `401`: The API key is missing or invalid.
- `403`: The API key doesn't have the scope this request needs.
- `429`: The API key made more requests per minute than its rate limit allows. Retry after the number of seconds in the `Retry-After` header.

Errors have a JSON body with a `message`, `details` and `hint`, and for database errors a `code`. See the [introduction](https://www.cv-transformer.com/en-GB/api-reference.md) for more on errors. The full API is described by the OpenAPI spec at https://api.cv-transformer.com/v1/openapi.json.