Skip to content
docs
Browse the docsWebhooks

API reference

Webhooks API

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

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

EndpointSummary
GET /v1/webhooksList webhooks
POST /v1/webhooksCreate a webhook
GET /v1/webhooks/{id}Get a webhook
PATCH /v1/webhooks/{id}Change a webhook
DELETE /v1/webhooks/{id}Delete a webhook

List webhooks

GET/v1/webhookswebhooks:managePro and up

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

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

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/webhookswebhooks:managePro and up

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)

NameTypeRequiredDescription
urlstringyesAn https:// address. At most 500 characters.
eventsstring[]yesOne or more events. One of message.received, inbox.created, inbox.expired.
secretstringno16 to 256 characters you choose, used to sign each delivery.
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"}'

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}webhooks:managePro and up

One endpoint with its last failure.

Path parameters

NameDescription
idThe webhook id.
curl "https://api.dissolve.email/v1/webhooks/$WEBHOOK_ID" \
  -H "Authorization: Bearer $DISSOLVE_API_KEY"

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}webhooks:managePro and up

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

Path parameters

NameDescription
idThe webhook id.

Body (application/json)

NameTypeRequiredDescription
urlstringnoA new https:// address.
eventsstring[]noThe events. One of message.received, inbox.created, inbox.expired.
secretstring or nullnoA new secret, or null to stop signing.
activebooleannoOn or off.
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}'

Response 200

JSON
{
  "success": true
}

Delete a webhook

DELETE/v1/webhooks/{id}webhooks:managePro and up

Removes the endpoint.

Path parameters

NameDescription
idThe webhook id.
curl -X DELETE "https://api.dissolve.email/v1/webhooks/$WEBHOOK_ID" \
  -H "Authorization: Bearer $DISSOLVE_API_KEY"

Response 200

JSON
{
  "success": true
}

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