Webhooks

Webhooks let you receive HTTP POST notifications when events happen in your account -- like an email being delivered, bounced, or a new inbound message arriving. You register an endpoint URL, and Molted Email sends events to it in real time.

Webhook endpoints are managed via /v1/me/webhooks. This requires session cookie auth when called directly, but is accessible with Bearer token auth through the agentic mailbox API proxy.

Registering a webhook

CLI (recommended)

molted webhooks create --url https://example.com/hooks/molted --events inbound.received,delivery.bounced

curl (via agentic mailbox API)

curl -X POST https://agentic-mailbox.molted.email/v1/me/webhooks?tenantId=TENANT_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/hooks/molted",
    "events": ["inbound.received", "delivery.bounced"],
    "description": "Production webhook"
  }'

Request body

Field	Type	Required	Description
`url`	`string`	Yes	The HTTPS URL to receive events.
`events`	`string[]`	No	Event types to subscribe to. Omit or pass `[]` to receive all events.
`description`	`string`	No	A label for this endpoint.

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "url": "https://example.com/hooks/molted",
  "secret": "whsec_a1b2c3d4e5f6...",
  "events": ["inbound.received", "delivery.bounced"],
  "enabled": true,
  "description": "Production webhook",
  "createdAt": "2026-03-01T12:00:00Z",
  "updatedAt": "2026-03-01T12:00:00Z"
}

Save the secret -- you will need it to verify signatures. It is only returned on create and when fetching a single endpoint.

Event types

Event	When it fires
`inbound.received`	New inbound email stored
`inbound.classified`	Inbound email classified by AI
`inbound.routed`	Inbound email routed to a thread
`delivery.sent`	Email sent to provider
`delivery.delivered`	Email confirmed delivered
`delivery.bounced`	Email bounced (triggers auto-suppression)
`delivery.complained`	Spam complaint received (triggers auto-suppression)

Payload format

Events are sent as HTTP POST requests with the following headers:

Header	Description
`Content-Type`	`application/json`
`X-Molted-Signature`	HMAC-SHA256 signature of the raw body
`X-Molted-Event`	Event type (e.g. `inbound.received`)
`X-Molted-Delivery`	Unique delivery ID

Payload body

{
  "event": "inbound.received",
  "timestamp": "2026-03-22T10:00:00Z",
  "data": {
    "messageId": "...",
    "from": "sender@example.com",
    "subject": "Hello"
  }
}

Verifying signatures

Every webhook payload is signed with your endpoint's secret using HMAC-SHA256. Always verify the signature before processing:

Node.js

const crypto = require('crypto');

function verifyWebhook(rawBody, signatureHeader, secret) {
  const signature = crypto
    .createHmac('sha256', secret)
    .update(rawBody) // must be raw bytes, not parsed JSON
    .digest('hex');

  const expected = signatureHeader.replace('sha256=', '');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Retries and delivery

Timeout: 5 seconds per attempt
Max attempts: 5
Backoff: Exponential (10s, 20s, 40s, 80s, 160s)
Success: HTTP 2xx response
Failure: After 5 failed attempts, the delivery is marked as failed

Managing endpoints

List endpoints

CLI

molted webhooks list

Get endpoint details

CLI

molted webhooks get --id ENDPOINT_ID

Returns the full endpoint object including secret.

Update an endpoint

CLI

molted webhooks update --id ENDPOINT_ID --enabled false

Updatable fields: --url, --events, --enabled, --description.

Delete an endpoint

CLI

molted webhooks delete --id ENDPOINT_ID

View delivery history

CLI

molted webhooks deliveries --id ENDPOINT_ID

Returns the 50 most recent deliveries with status (pending, delivered, failed), HTTP status code, and attempt count.

Send a test event

CLI

molted webhooks test --id ENDPOINT_ID

Sends a test event to your endpoint URL and returns the result:

Success

{
  "success": true,
  "httpStatus": 200,
  "deliveryId": "..."
}

Local development

Use molted webhooks listen to receive webhook events on your local machine during development:

CLI

molted webhooks listen --port 9876 --events inbound.received

This starts a local HTTP server, registers a temporary webhook endpoint pointing to it, and prints incoming events to stdout in formatted JSON. The temporary endpoint is automatically cleaned up when you stop listening (Ctrl-C).

On this page