# Webhooks API

> Signed HTTPS deliveries for new mail and inbox events. Every webhooks endpoint with its scope, parameters, body and an example answer.

Source: https://docs.dissolve.email/reference/webhooks

Base URL `https://api.dissolve.email`. Send an API key or OAuth access token as `Authorization: Bearer <token>` ([Authentication](/authentication)); an OAuth token needs the scope on each endpoint. Errors follow [one shape](/errors).

| Endpoint | Summary |
|---|---|
| `GET /v1/webhooks` | [List webhooks](#list-webhooks) |
| `POST /v1/webhooks` | [Create a webhook](#create-a-webhook) |
| `GET /v1/webhooks/{id}` | [Get a webhook](#get-a-webhook) |
| `PATCH /v1/webhooks/{id}` | [Change a webhook](#change-a-webhook) |
| `DELETE /v1/webhooks/{id}` | [Delete a webhook](#delete-a-webhook) |

### List webhooks

`GET /v1/webhooks` (scope `webhooks:manage`)

Your webhook endpoints, newest first (at most 10).

```bash cURL
curl "https://api.dissolve.email/v1/webhooks" \
  -H "Authorization: Bearer $DISSOLVE_API_KEY"
```

```ts TypeScript
import { Dissolve } from '@dissolve-email/sdk';

const client = new Dissolve(); // reads DISSOLVE_API_KEY
const result = await client.v1.listWebhooks();
```

```python Python
import os, requests

API_KEY = os.environ["DISSOLVE_API_KEY"]
response = requests.get("https://api.dissolve.email/v1/webhooks", headers={"Authorization": f"Bearer {API_KEY}"})
print(response.json())
```

**Response** `200`

```json
[
  {
    "id": "whk2Lp9QsX4nVb7Tc1RzM",
    "url": "https://example.com/hooks/dissolve",
    "events": [
      "message.received"
    ],
    "active": true,
    "failureCount": 0,
    "lastTriggeredAt": null,
    "createdAt": "2026-11-19T10:00:00.000Z"
  }
]
```

### Create a webhook

`POST /v1/webhooks` (scope `webhooks:manage`)

Registers an HTTPS endpoint for one or more events. With a `secret` every delivery is signed in `X-Webhook-Signature: sha256=<hex>`. Addresses on private networks are refused.

**Body** (`application/json`)

| Name | Type | Required | Description |
|---|---|---|---|
| `url` | string | yes | An https:// address. At most 500 characters. |
| `events` | string[] | yes | One or more events. One of `message.received`, `inbox.created`, `inbox.expired`. |
| `secret` | string | no | 16 to 256 characters you choose, used to sign each delivery. |

```bash cURL
curl -X POST "https://api.dissolve.email/v1/webhooks" \
  -H "Authorization: Bearer $DISSOLVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/hooks/dissolve","events":["message.received"],"secret":"a-long-random-secret-you-keep"}'
```

```ts TypeScript
import { Dissolve } from '@dissolve-email/sdk';

const client = new Dissolve(); // reads DISSOLVE_API_KEY
const result = await client.v1.createWebhook({
  url: "https://example.com/hooks/dissolve",
  events: [
    "message.received"
  ],
  secret: "a-long-random-secret-you-keep"
});
```

```python Python
import os, requests

API_KEY = os.environ["DISSOLVE_API_KEY"]
response = requests.post("https://api.dissolve.email/v1/webhooks", json={
  "url": "https://example.com/hooks/dissolve",
  "events": [
    "message.received"
  ],
  "secret": "a-long-random-secret-you-keep"
}, headers={"Authorization": f"Bearer {API_KEY}"})
print(response.json())
```

**Response** `201`

```json
{
  "id": "whk2Lp9QsX4nVb7Tc1RzM",
  "url": "https://example.com/hooks/dissolve",
  "events": [
    "message.received"
  ],
  "active": true,
  "createdAt": "2026-11-19T10:00:00.000Z"
}
```

### Get a webhook

`GET /v1/webhooks/{id}` (scope `webhooks:manage`)

One endpoint with its last failure.

**Path parameters**

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

```bash cURL
curl "https://api.dissolve.email/v1/webhooks/$WEBHOOK_ID" \
  -H "Authorization: Bearer $DISSOLVE_API_KEY"
```

```ts TypeScript
import { Dissolve } from '@dissolve-email/sdk';

const client = new Dissolve(); // reads DISSOLVE_API_KEY
const result = await client.v1.getWebhook(webhookId);
```

```python Python
import os, requests

API_KEY = os.environ["DISSOLVE_API_KEY"]
response = requests.get(f"https://api.dissolve.email/v1/webhooks/{webhook_id}", headers={"Authorization": f"Bearer {API_KEY}"})
print(response.json())
```

**Response** `200`

```json
{
  "id": "whk2Lp9QsX4nVb7Tc1RzM",
  "url": "https://example.com/hooks/dissolve",
  "events": [
    "message.received"
  ],
  "active": true,
  "failureCount": 0,
  "lastTriggeredAt": null,
  "createdAt": "2026-11-19T10:00:00.000Z",
  "lastFailureAt": null,
  "lastFailureReason": null
}
```

### Change a webhook

`PATCH /v1/webhooks/{id}` (scope `webhooks:manage`)

Changes the address, events or secret, or switches it on or off. Switching it on clears the failure count.

**Path parameters**

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

**Body** (`application/json`)

| Name | Type | Required | Description |
|---|---|---|---|
| `url` | string | no | A new https:// address. |
| `events` | string[] | no | The events. One of `message.received`, `inbox.created`, `inbox.expired`. |
| `secret` | string or null | no | A new secret, or null to stop signing. |
| `active` | boolean | no | On or off. |

```bash cURL
curl -X PATCH "https://api.dissolve.email/v1/webhooks/$WEBHOOK_ID" \
  -H "Authorization: Bearer $DISSOLVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"active":true}'
```

```ts TypeScript
import { Dissolve } from '@dissolve-email/sdk';

const client = new Dissolve(); // reads DISSOLVE_API_KEY
const result = await client.v1.updateWebhook(webhookId, {
  active: true
});
```

```python Python
import os, requests

API_KEY = os.environ["DISSOLVE_API_KEY"]
response = requests.patch(f"https://api.dissolve.email/v1/webhooks/{webhook_id}", json={
  "active": True
}, headers={"Authorization": f"Bearer {API_KEY}"})
print(response.json())
```

**Response** `200`

```json
{
  "success": true
}
```

### Delete a webhook

`DELETE /v1/webhooks/{id}` (scope `webhooks:manage`)

Removes the endpoint.

**Path parameters**

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

```bash cURL
curl -X DELETE "https://api.dissolve.email/v1/webhooks/$WEBHOOK_ID" \
  -H "Authorization: Bearer $DISSOLVE_API_KEY"
```

```ts TypeScript
import { Dissolve } from '@dissolve-email/sdk';

const client = new Dissolve(); // reads DISSOLVE_API_KEY
const result = await client.v1.deleteWebhook(webhookId);
```

```python Python
import os, requests

API_KEY = os.environ["DISSOLVE_API_KEY"]
response = requests.delete(f"https://api.dissolve.email/v1/webhooks/{webhook_id}", headers={"Authorization": f"Bearer {API_KEY}"})
print(response.json())
```

**Response** `200`

```json
{
  "success": true
}
```
