Webhooks
Configure webhook endpoints and verify signed deliveries from Taifa Mail.
Webhooks let you register HTTPS endpoints that receive signed JSON when Taifa Mail events occur. Use them to drive automations, update case systems, or pipe forwarded inbound mail into your own app.
Live outbound event delivery is not wired yet. Registering a webhook and selecting event types such as email.delivered or email.opened does not cause automatic deliveries today. What works now:
- Send test:
POST /v1/webhooks/{id}/test(or Send test in the dashboard) queues a sampleemail.deliveredpayload. - Inbound forward: when a forwarding rule delivers to an HTTPS URL, Taifa Mail POSTs an
email.inbound.forwardedevent.
Opens, clicks, bounces, and other outbound lifecycle events are visible under Developer → Email Logs and over the API until live webhook fan-out ships.
Use cases
- Confirm your endpoint verifies signatures before you rely on it in production.
- Receive inbound mail forwarded to your CRM or case-management system.
- Drive workflows in n8n, Zapier, or Make once live event delivery is enabled.
Step 1: Add an endpoint
- In the dashboard, go to Developer → Webhooks.
- Click Add webhook and enter a public HTTPS URL. Plain HTTP and private addresses are rejected.
- Select the event types you want (stored for when live delivery is enabled).
- Copy the signing secret from the create response.
Step 2: Verify the signature
Each delivery carries an X-TaifaMail-Signature header: an HMAC-SHA256 digest over the timestamp, delivery ID, event type, and raw JSON body, signed with your secret. Recompute and compare in constant time before trusting the payload. See the Webhooks API reference for language examples.
Step 3: Send a test
Click Send test next to any webhook (or call POST /v1/webhooks/{webhook_id}/test) to queue a sample email.delivered delivery. The attempt appears under that webhook's Deliveries tab.
Failed deliveries retry on a schedule (1m, 5m, 30m, 2h, 8h) when your endpoint returns a non-2xx response.