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.
| Endpoint | Summary |
|---|---|
GET /v1/webhooks | List webhooks |
POST /v1/webhooks | Create 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
/v1/webhookswebhooks:managePro and upYour webhook endpoints, newest first (at most 10).
curl "https://api.dissolve.email/v1/webhooks" \
-H "Authorization: Bearer $DISSOLVE_API_KEY"import { Dissolve } from '@dissolve-email/sdk';
const client = new Dissolve(); // reads DISSOLVE_API_KEY
const result = await client.v1.listWebhooks();import os, requests
API_KEY = os.environ["DISSOLVE_API_KEY"]
response = requests.get("https://api.dissolve.email/v1/webhooks", headers={"Authorization": f"Bearer {API_KEY}"})
print(response.json())Response 200
[
{
"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
/v1/webhookswebhooks:managePro and upRegisters 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)
| Name | Type | Required | Description |
|---|---|---|---|
url | string | yes | An https:// address. At most 500 characters. |
events | string[] | yes | One or more events. One of message.received, inbox.created, inbox.expired. |
secret | string | no | 16 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"}'import { Dissolve } from '@dissolve-email/sdk';
const client = new Dissolve(); // reads DISSOLVE_API_KEY
const result = await client.v1.createWebhook({
url: "https://example.com/hooks/dissolve",
events: [
"message.received"
],
secret: "a-long-random-secret-you-keep"
});import os, requests
API_KEY = os.environ["DISSOLVE_API_KEY"]
response = requests.post("https://api.dissolve.email/v1/webhooks", json={
"url": "https://example.com/hooks/dissolve",
"events": [
"message.received"
],
"secret": "a-long-random-secret-you-keep"
}, headers={"Authorization": f"Bearer {API_KEY}"})
print(response.json())Response 201
{
"id": "whk2Lp9QsX4nVb7Tc1RzM",
"url": "https://example.com/hooks/dissolve",
"events": [
"message.received"
],
"active": true,
"createdAt": "2026-11-19T10:00:00.000Z"
}Get a webhook
/v1/webhooks/{id}webhooks:managePro and upOne endpoint with its last failure.
Path parameters
| Name | Description |
|---|---|
id | The webhook id. |
curl "https://api.dissolve.email/v1/webhooks/$WEBHOOK_ID" \
-H "Authorization: Bearer $DISSOLVE_API_KEY"import { Dissolve } from '@dissolve-email/sdk';
const client = new Dissolve(); // reads DISSOLVE_API_KEY
const result = await client.v1.getWebhook(webhookId);import os, requests
API_KEY = os.environ["DISSOLVE_API_KEY"]
response = requests.get(f"https://api.dissolve.email/v1/webhooks/{webhook_id}", headers={"Authorization": f"Bearer {API_KEY}"})
print(response.json())Response 200
{
"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
/v1/webhooks/{id}webhooks:managePro and upChanges the address, events or secret, or switches it on or off. Switching it on clears the failure count.
Path parameters
| Name | Description |
|---|---|
id | The webhook id. |
Body (application/json)
| Name | Type | Required | Description |
|---|---|---|---|
url | string | no | A new https:// address. |
events | string[] | no | The events. One of message.received, inbox.created, inbox.expired. |
secret | string or null | no | A new secret, or null to stop signing. |
active | boolean | no | On 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}'import { Dissolve } from '@dissolve-email/sdk';
const client = new Dissolve(); // reads DISSOLVE_API_KEY
const result = await client.v1.updateWebhook(webhookId, {
active: true
});import os, requests
API_KEY = os.environ["DISSOLVE_API_KEY"]
response = requests.patch(f"https://api.dissolve.email/v1/webhooks/{webhook_id}", json={
"active": True
}, headers={"Authorization": f"Bearer {API_KEY}"})
print(response.json())Response 200
{
"success": true
}Delete a webhook
/v1/webhooks/{id}webhooks:managePro and upRemoves the endpoint.
Path parameters
| Name | Description |
|---|---|
id | The webhook id. |
curl -X DELETE "https://api.dissolve.email/v1/webhooks/$WEBHOOK_ID" \
-H "Authorization: Bearer $DISSOLVE_API_KEY"import { Dissolve } from '@dissolve-email/sdk';
const client = new Dissolve(); // reads DISSOLVE_API_KEY
const result = await client.v1.deleteWebhook(webhookId);import os, requests
API_KEY = os.environ["DISSOLVE_API_KEY"]
response = requests.delete(f"https://api.dissolve.email/v1/webhooks/{webhook_id}", headers={"Authorization": f"Bearer {API_KEY}"})
print(response.json())Response 200
{
"success": true
}Something wrong or missing on this page? Tell us at support@dissolve.email.View as Markdown