MailStack
Documentation

API reference / Token auth

Webhooks

Subscribe to delivery events, inspect the delivery feed, replay failed deliveries, and verify signatures with the shared secret.

MethodPathDescription
GET/v1/webhooksList webhooks (secrets masked).
GET/v1/webhooks/{id}Get one webhook (secret masked).
POST/v1/webhooksCreate a webhook (full signing secret returned once).
PUT/v1/webhooks/{id}Update a webhook’s URL, events, and enabled flag.
DELETE/v1/webhooks/{id}Delete a webhook.
POST/v1/webhooks/{id}/rotate-secretRotate the signing secret (new secret returned once).
GET/v1/webhooks/{id}/deliveriesRecent delivery attempts (newest first).
POST/v1/webhooks/deliveries/{id}/replayReplay a delivery — re-enqueue the same (webhook, event).

GET /v1/webhooks

Token + X-MailStack-Org

List webhooks (secrets masked).

Response

[ { "id": "...", "url": "https://example.com/hooks", "eventTypes": "*", "enabled": true, "secretHint": "••••abcd" } ]

GET /v1/webhooks/{id}

Token + X-MailStack-Org

Get one webhook (secret masked).

POST /v1/webhooks

Token + X-MailStack-Org

eventTypes is a comma-separated list of event-type names (Sent, Delivered, Bounce, Complaint, Open, Click, Reject, DeliveryDelay) or "*" for all. The signingSecret (whsec_…) is returned exactly once.

Request body

{ "url": "https://example.com/hooks", "eventTypes": "Delivered,Bounce,Complaint", "enabled": true }

Response

{
  "webhook": { "id": "...", "url": "https://example.com/hooks", "eventTypes": "Delivered,Bounce,Complaint", "enabled": true, "secretHint": "••••abcd" },
  "signingSecret": "whsec_..."
}
POST /v1/webhooks 
curl https://api.mailstack.voostack.com/v1/webhooks \
  -H "Authorization: Bearer <jwt>" \
  -H "X-MailStack-Org: org_..." \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/hooks", "eventTypes": "Delivered,Bounce" }'

PUT /v1/webhooks/{id}

Token + X-MailStack-Org

Update a webhook’s URL, events, and enabled flag.

Request body

{ "url": "https://example.com/hooks", "eventTypes": "*", "enabled": false }

DELETE /v1/webhooks/{id}

Token + X-MailStack-Org

Delete a webhook.

Response

{ "status": "ok" }

POST /v1/webhooks/{id}/rotate-secret

Token + X-MailStack-Org

Rotate the signing secret (new secret returned once).

Response

{ "webhook": { "id": "..." }, "signingSecret": "whsec_..." }

GET /v1/webhooks/{id}/deliveries

Token + X-MailStack-Org

Query param: limit (1–200, default 50).

Response

[ { "id": "...", "webhookId": "...", "messageEventId": "...", "statusCode": 200, "attempt": 1, "succeeded": true } ]

POST /v1/webhooks/deliveries/{id}/replay

Token + X-MailStack-Org

Replay a delivery — re-enqueue the same (webhook, event).

Response

{ "status": "ok" }

SDKs

Prefer a typed client? The Webhooks endpoints are covered by the official Node, .NET, Go, and Flutter/Dart SDKs.