# Webhooks

> Be called when something happens in your organization, and read the deliveries.

A webhook is a URL Rytiv calls for events of your organization. Each delivery is recorded and can be read back.

## Endpoints

- [`POST /v1/webhooks`](#post-v1webhooks): Registers a webhook URL
- [`GET /v1/webhooks`](#get-v1webhooks): The organization's webhooks
- [`GET /v1/webhooks/:id`](#get-v1webhooksid): One webhook
- [`GET /v1/webhooks/:id/deliveries`](#get-v1webhooksiddeliveries): Its deliveries with their status
- [`DELETE /v1/webhooks/:id`](#delete-v1webhooksid): Removes the webhook

## POST /v1/webhooks

Registers a webhook URL.

**Auth:** API key with full access (a key with scopes cannot call this route). Refused for every agent token (`agent-token-credential`).

### Request body

JSON, the shape `CreateWebhookRequest` of the contract.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | required | 1 to 2048 characters. |
| `events` | array of `email.sent` \| `email.delivered` \| `email.delivery_delayed` \| `email.bounced` \| `email.complained` \| `email.failed` \| `email.received` | required | 1 to any number of items. |

### Example request

```bash
curl -X POST "https://api.rytiv.app/v1/webhooks" \
  -H "Authorization: Bearer $RYTIV_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"<url>","events":["email.sent"]}'
```

### Response

`201` with a JSON object carrying `secret` and the fields of the object the handler builds.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `bad-request` | The request is malformed or a field is out of range. `error` names every field; `issues` lists them. |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |

## GET /v1/webhooks

The organization's webhooks.

**Auth:** API key with full access or the scope `read`. Every class of agent token may call it.

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/webhooks" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with a JSON body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |

## GET /v1/webhooks/:id

One webhook.

**Auth:** API key with full access or the scope `read`. Every class of agent token may call it.

### Path parameters

| Name | Description |
| --- | --- |
| `id` | The webhook's id. |

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/webhooks/<id>" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with a JSON body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## GET /v1/webhooks/:id/deliveries

Its deliveries with their status.

**Auth:** API key with full access or the scope `read`. An agent token of class `production` needs `prodDataRead` for it; `sandbox` and `twin` may call it.

### Path parameters

| Name | Description |
| --- | --- |
| `id` | The object's id. |

### Query parameters

| Name | Description |
| --- | --- |
| `limit` | How many entries, at most. |

### Example request

```bash
curl -X GET "https://api.rytiv.app/v1/webhooks/<id>/deliveries" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`200` with a JSON body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |

## DELETE /v1/webhooks/:id

Removes the webhook.

**Auth:** API key with full access (a key with scopes cannot call this route). Refused for every agent token (`agent-token-credential`).

### Path parameters

| Name | Description |
| --- | --- |
| `id` | The webhook's id. |

### Example request

```bash
curl -X DELETE "https://api.rytiv.app/v1/webhooks/<id>" \
  -H "Authorization: Bearer $RYTIV_TOKEN"
```

### Response

`204` with no body.

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthenticated` | No API key, or one that does not work. |
| 403 | `token-scope` | The key's scopes do not cover this route. |
| 404 | `not-found` | Not found, or not yours. An object of another organization answers like one that does not exist. |