# Webhooks

> Get an HTTPS call when mail arrives or an inbox is made or expires. The events and their payloads, signature checks in TypeScript and Python, retries and testing.

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

A webhook is an HTTPS address of yours that dissolve.email calls when something happens, so you do not have to hold a request open or poll. Webhooks are on Pro and Business; an account may have 10.

| Event | Sent when |
|---|---|
| `message.received` | A message is stored in one of your inboxes |
| `inbox.created` | You make an inbox |
| `inbox.expired` | One of your inboxes reaches its expiry and is deleted |

## Create a webhook

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

| Field | What it does |
|---|---|
| `url` | Required. An `https://` address, at most 500 characters. Addresses on private or internal networks are refused. |
| `events` | Required. One or more of the events above. |
| `secret` | 16 to 256 characters you choose. With one, every delivery is signed. |

```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();
const webhook = await client.v1.createWebhook({
  url: 'https://example.com/hooks/dissolve',
  events: ['message.received'],
  secret: process.env.DISSOLVE_WEBHOOK_SECRET,
});
```

```python Python
import os, requests

HEADERS = {"Authorization": f"Bearer {os.environ['DISSOLVE_API_KEY']}"}
webhook = requests.post(
    "https://api.dissolve.email/v1/webhooks",
    json={"url": "https://example.com/hooks/dissolve", "events": ["message.received"], "secret": os.environ["DISSOLVE_WEBHOOK_SECRET"]},
    headers=HEADERS,
).json()
```

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

The secret is never shown again: keep it where your receiver can read it. Registering the same address twice answers `400 conflict`.

## What a delivery looks like

Each delivery is a `POST` with a JSON body:

```http
POST /hooks/dissolve HTTP/1.1
Content-Type: application/json
User-Agent: dissolve.email-Webhook/1.0
X-Webhook-Id: whk2Lp9QsX4nVb7Tc1RzM
X-Webhook-Event: message.received
X-Delivery-Id: dlv8Rk2Tq5Wm1Zx7Vc3Np
X-Webhook-Signature: sha256=6f1c0b9e...
```

```json
{
  "event": "message.received",
  "timestamp": "2026-11-19T10:02:12.031Z",
  "data": {
    "messageId": "Qm8wZ1kX0pLr7aYtV3nBc",
    "inboxId": "V1StGXR8Z5jdHi6BmyT2k",
    "inboxAddress": "signup-test@dissolve.email",
    "from": "noreply@github.com",
    "subject": "Your GitHub launch code",
    "receivedAt": "2026-11-19T10:02:11.000Z"
  }
}
```

| Event | `data` |
|---|---|
| `message.received` | `messageId`, `inboxId`, `inboxAddress`, `from`, `subject`, `receivedAt` |
| `inbox.created` | `inboxId`, `address`, `domain`, `expiresAt` |
| `inbox.expired` | `inboxId`, `address`, `domain`, `expiredAt` |

The body is never in the payload: fetch the message with [Get a message](/messages#read-a-message) if you need it. `X-Delivery-Id` is the same on every retry of one delivery, so you can drop a repeat.

## Check the signature

With a secret, `X-Webhook-Signature` is `sha256=` followed by the hex HMAC-SHA256 of the raw request body, keyed with your secret. Compute it over the bytes you received, before parsing the JSON, and compare in constant time. Refuse anything that does not match.

```ts TypeScript
import { createHmac, timingSafeEqual } from 'node:crypto';

export function verifySignature(rawBody: string, header: string | null, secret: string): boolean {
  if (!header?.startsWith('sha256=')) return false;
  const expected = createHmac('sha256', secret).update(rawBody).digest('hex');
  const given = header.slice('sha256='.length);
  return given.length === expected.length && timingSafeEqual(Buffer.from(given), Buffer.from(expected));
}

// In a Worker or any runtime with Web Crypto:
export async function verifySignatureWeb(rawBody: string, header: string | null, secret: string): Promise<boolean> {
  if (!header?.startsWith('sha256=')) return false;
  const key = await crypto.subtle.importKey('raw', new TextEncoder().encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['verify']);
  const hex = header.slice('sha256='.length);
  const bytes = new Uint8Array((hex.match(/../g) ?? []).map((pair) => parseInt(pair, 16)));
  return crypto.subtle.verify('HMAC', key, bytes, new TextEncoder().encode(rawBody));
}
```

```python Python
import hashlib, hmac

def verify_signature(raw_body: bytes, header: str | None, secret: str) -> bool:
    if not header or not header.startswith("sha256="):
        return False
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(header[len("sha256="):], expected)
```

> [!WARNING] Answer fast
> Reply with any 2xx within 10 seconds, then do the work. A slow answer counts as a failure and is sent again.

## Retries and failures

- A delivery that does not get a 2xx (a timeout, an error status or a redirect, since redirects are not followed) is tried again after 30 seconds, then 60, 120 and so on, doubling up to an hour between tries.
- Five failures in a row switch the webhook off (`active: false`). Fix your receiver, then switch it back on with `PATCH /v1/webhooks/{id}` and `{"active": true}`, which also clears the count.
- The address is checked again before each delivery, so one that has come to point at a private network is not called.

## Send a test

`POST /api/user-webhooks/{id}/test` (API key or signed-in session)

Queues one delivery with `event: "test"` to the webhook, on the same path as real events, and answers `202` with its `deliveryId`. Twenty tests an hour. It takes an API key or the signed-in app; it is not part of `/v1`.

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

```json
{ "event": "test", "timestamp": "2026-11-19T10:05:00.000Z", "data": { "message": "This is a test webhook delivery", "webhookId": "whk2Lp9QsX4nVb7Tc1RzM" } }
```

## Manage webhooks

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

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

One webhook adds `lastFailureAt` and `lastFailureReason`, which say why the last try failed.

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

Change `url`, `events`, `secret` (or `null` to stop signing) and `active`.

```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
await client.v1.updateWebhook(webhookId, { active: true });
```

```python Python
requests.patch(f"https://api.dissolve.email/v1/webhooks/{webhook_id}", json={"active": True}, headers=HEADERS)
```

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

> [!NOTE] Scope
> Every webhook endpoint needs `webhooks:manage`. API keys have it.
