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.
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/webhookswebhooks:managePro and up
| 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. |
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"}'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,
});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(){ "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:
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...{
"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 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.
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));
}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)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 withPATCH /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
/api/user-webhooks/{id}/testAPI key or sessionQueues 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.
curl -X POST https://api.dissolve.email/api/user-webhooks/$WEBHOOK_ID/test \
-H "Authorization: Bearer $DISSOLVE_API_KEY"{ "event": "test", "timestamp": "2026-11-19T10:05:00.000Z", "data": { "message": "This is a test webhook delivery", "webhookId": "whk2Lp9QsX4nVb7Tc1RzM" } }Manage webhooks
GET/v1/webhookswebhooks:managePro and up
GET/v1/webhooks/{id}webhooks:managePro and up
One webhook adds lastFailureAt and lastFailureReason, which say why the last try failed.
/v1/webhooks/{id}webhooks:managePro and up
Change url, events, secret (or null to stop signing) and active.
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}'await client.v1.updateWebhook(webhookId, { active: true });requests.patch(f"https://api.dissolve.email/v1/webhooks/{webhook_id}", json={"active": True}, headers=HEADERS)/v1/webhooks/{id}webhooks:managePro and up
Something wrong or missing on this page? Tell us at support@dissolve.email.View as Markdown