Skip to content
docs
Browse the docsWebhooks

Mail

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.

EventSent when
message.receivedA message is stored in one of your inboxes
inbox.createdYou make an inbox
inbox.expiredOne of your inboxes reaches its expiry and is deleted

Create a webhook

POST/v1/webhookswebhooks:managePro and up
FieldWhat it does
urlRequired. An https:// address, at most 500 characters. Addresses on private or internal networks are refused.
eventsRequired. One or more of the events above.
secret16 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"}'
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"
  }
}
Eventdata
message.receivedmessageId, inboxId, inboxAddress, from, subject, receivedAt
inbox.createdinboxId, address, domain, expiresAt
inbox.expiredinboxId, 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));
}

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}/testAPI key or 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.

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/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.

PATCH/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}'
DELETE/v1/webhooks/{id}webhooks:managePro and up

Something wrong or missing on this page? Tell us at support@dissolve.email.View as Markdown