What The Hooks API Is
Mailbase exposes a REST Hooks surface under /api/hooks. A visual builder registers a callback URL for one event type, receives a signed POST every time that event happens, and deletes the registration when the user switches the automation off. This is what Zapier, Make, and n8n expect from a platform; it is not the same thing as pasting a webhook URL into Settings.
A subscription is backed by a normal Mailbase webhook endpoint, so it appears in Settings alongside endpoints your team added by hand, it is signed with the same HMAC scheme, and its deliveries show up in the same delivery log.
| Endpoint | Method | Purpose |
|---|---|---|
| /api/hooks/events | GET | List subscribable event types with human descriptions and their sample fields. |
| /api/hooks/subscribe | POST | Register a callback URL for one event. Returns the subscription id. |
| /api/hooks/subscribe | GET | List the current workspace's subscriptions. |
| /api/hooks/subscribe/{id} | DELETE | Unsubscribe. Called when the automation is turned off. |
| /api/hooks/sample?event= | GET | Recent real payloads for one event, so the builder can render field names. |
Auth Model
Every /api/hooks endpoint uses the same bearer API tokens as /api/v1. Create a token in Settings, then send it as an Authorization header. The token is pinned to one workspace, so a subscription can only ever receive events from the workspace whose token created it.
All four endpoints require the webhooks:write scope. Sampling is included in that scope because anyone who can subscribe can already receive the same payloads.
curl -X POST https://mailbase.example.com/api/hooks/subscribe \
-H "Authorization: Bearer $MAILBASE_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"event":"email.clicked","targetUrl":"https://hooks.zapier.com/hooks/catch/123/abc/","client":"zapier"}'Connect Zapier, Make, Or n8n
- Create an API token in Settings with the webhooks:write scope, and keep it in the tool's credential store rather than in a step body.
- Point the tool's subscribe action at POST /api/hooks/subscribe with the event and the tool's own catch URL as targetUrl, and store the returned id.
- Point the unsubscribe action at DELETE /api/hooks/subscribe/{id} using that stored id.
- Point the sample or list action at GET /api/hooks/sample?event=... so the field picker has data before the first real event arrives.
- In n8n, a Webhook node's production URL is the targetUrl. In Make, use the custom webhook address. In Zapier, use the REST Hook subscribe and unsubscribe URLs.
Subscribable Events
One subscription watches exactly one event. Subscribe more than once to watch more than one.
| Event | Fires when |
|---|---|
| email.sent | Email accepted by the provider. |
| email.delivered | Email delivered by the provider. |
| email.opened | Human open recorded. |
| email.clicked | Human click recorded. |
| email.bounced | Bounce recorded. |
| email.complained | Complaint recorded. |
| email.unsubscribed | Unsubscribe recorded. |
| reply.received | Inbound reply received. |
| audience.created | Audience or dynamic segment created. |
| campaign.launched | Campaign send launched. |
Payloads And Signatures
Deliveries are POSTed as JSON with an envelope of id, type, created_at, workspace_id, and data. The Mailbase-Event, Mailbase-Delivery, Mailbase-Timestamp, and Mailbase-Signature headers accompany every request. The signature is an HMAC-SHA256 of the timestamp, a dot, and the raw body, using the signing secret returned once when the subscription was created.
GET /api/hooks/sample returns a bare JSON array. When the workspace has recent history for that event you get real envelopes; otherwise you get one synthetic envelope of the same shape, flagged with sample: true. The Mailbase-Sample-Source response header says which you received.
Lifecycle Rules
- Subscribing twice with the same event and callback URL returns the existing subscription instead of creating a duplicate, so a retried call cannot double your deliveries.
- A callback URL that answers 410 Gone is unsubscribed immediately and its endpoint is removed. This is how an automation deleted on the tool's side stops receiving traffic.
- Deleting the endpoint in Settings also ends the subscription. The tool's next unsubscribe call then returns 404, which builders treat as already removed.
- Each workspace can hold up to 40 hook subscriptions.
Callback URL Rules
Mailbase makes outbound requests to whatever callback URL you register, so the URL is validated before it is stored and the checks are deliberately strict.
- https only. Plain http, and any other scheme, is rejected.
- No credentials in the URL, and no privileged port other than 443.
- No literal address inside a private, loopback, link-local, carrier-grade NAT, multicast, or reserved range, including the IPv6 and IPv4-in-IPv6 spellings of those ranges.
- No localhost, no single-label hostname, and no local-only suffix such as .local or .internal.
- The hostname is resolved when you subscribe and rejected if any answer falls inside a non-public range, so a public name pointed at an internal address is refused too.