Monitor · Webhooks
Email Webhooks API
Receive real-time HTTP callbacks when email events occur: delivered, bounced, complained, opened, or clicked. JSON payloads delivered to your endpoint with HMAC signature verification.
Representative product UI — illustrative data, not live customer metrics.
From black box to event stream
Email Webhooks for Developer Teams
Build event-driven workflows without polling. Automatic retry handling ensures events are delivered even when your endpoint is temporarily unavailable.
# Send a critical email through a routing policy curl -sS -X POST 'https://app.sendarix.com/v1/email/send' \ -H 'Content-Type: application/json' \ -H 'X-API-Key: YOUR_API_KEY' \ -H 'Idempotency-Key: otp_8842' \ -d '{"to":"user@acme.com","template":"password_reset","routing_policy":"transactional-critical"}'
const sendarix = require("sendarix")(process.env.SENDARIX_KEY); await sendarix.email.send({ to: "user@acme.com", template: "password_reset", routingPolicy: "transactional-critical", idempotencyKey: "otp_8842" });
# Drop-in SMTP — keep your integration, gain a control plane host: smtp.sendarix.com port: 587 (STARTTLS) username: "your_sending_key" header: X-Sendarix-Policy: transactional-critical
Webhook Capabilities
Webhooks turn email from a black box into an event stream your product can reason about in real time. Combine webhook event data with deliverability monitoring to catch reputation issues before they escalate.
Delivery State Sync
Update user-facing status as messages move from accepted to delivered or bounced.
Failure Automation
Trigger retry paths and internal alerts when transient or permanent failures are detected.
Reputation Protection
Handle complaint and bounce events automatically to keep bad addresses out of future sends.
Workflow Integrations
Feed events into CRM, data warehouse, queue workers, and incident response systems.
Signature Verification
Validate incoming webhook signatures so only trusted Sendarix events are processed.
Retry-Safe Consumers
Design idempotent handlers that safely process duplicate deliveries and delayed events.
Webhook Lifecycle
A straightforward flow for building reliable event-driven automations.
1. Send Message
Message enters the delivery pipeline through API or SMTP.
2. Event Generated
Delivery system creates status events (accepted, delivered, bounced, complained).
3. Webhook Delivered
Events are posted to your endpoint for immediate processing.
4. App Reacts
Your systems update user state, trigger jobs, or notify teams automatically.
Frequently Asked Questions
Can webhooks replace polling completely?
For most event-driven workflows, yes. Teams still use analytics for historical analysis and reporting.
Which events are most important to start with?
Start with delivered, bounced, and complained. Then expand to engagement or custom workflow events.
Are webhooks only for large systems?
No. Even small apps benefit from immediate state sync and reduced manual support debugging.
How should we verify webhook requests are genuine?
Use shared secrets, signatures, or HMAC headers where provided, validate timestamps to block replays, and reject payloads that fail checks before updating production state.
What if our endpoint is down when a webhook fires?
Rely on retry policies and make handlers idempotent. Log received event IDs so duplicates from retries do not corrupt your database or user notifications.
Should webhook processing happen synchronously in the HTTP request?
Usually no. Acknowledge quickly, enqueue work to a job runner, and process asynchronously so slow tasks do not cause timeouts and unnecessary retries.
Can we fan out the same event to multiple internal services?
Yes, via a message bus or router. Keep a single ingress that validates and normalizes payloads, then distribute to billing, CRM, data warehouse, or alerting consumers.
How do webhooks help with bounce and complaint handling?
They let you update suppression lists, pause risky campaigns, or flag accounts in near real time instead of discovering problems hours later through support tickets.
Do we need separate webhook URLs for staging and production?
Strongly recommended. Isolated endpoints prevent test events from touching live user data and make it easier to rotate credentials independently.
What is the format of webhook payloads?
All payloads are JSON with a consistent envelope: event type, timestamp, message ID, and event-specific data. See the Payload Examples section for full schemas.
What happens if our endpoint returns a non-2xx response?
Any response outside the 2xx range triggers a retry. Timeouts, connection refusals, and DNS failures also count as failures and trigger retry logic.
How long does Sendarix wait for our endpoint to respond?
Default timeout is 10 seconds. If your endpoint does not respond within this window, the request is considered failed and enters the retry queue.
Can we filter which events we receive?
Yes. Configure event type filters per endpoint to receive only the events relevant to your integration (e.g., bounces and complaints only).
What HTTP methods does Sendarix use for webhook delivery?
Sendarix sends POST requests only. If your endpoint receives a GET, PUT, PATCH, or DELETE request to the webhook URL, return 405 Method Not Allowed. This prevents accidental processing of unrelated traffic that may hit your endpoint.
How do we handle webhooks during deployment downtime?
Sendarix queues events during the retry window. If your endpoint is down for less than 5 hours, all events are preserved and delivered when your endpoint returns. For extended downtime (maintenance windows, incidents), queue events in Sendarix and process them after recovery via the event replay API.
Should our webhook endpoint be idempotent across different event types?
Yes. Process the event_id regardless of event_type. A given event_id represents one specific event (e.g., evt_abc123 = bounce for msg_xyz). If you receive evt_abc123 twice, return 200 OK on the second attempt without reprocessing. The event_id is globally unique across all event types.
How do we test webhooks in a staging environment without affecting production data?
Configure a separate webhook endpoint in your staging environment with its own secret. Use the Sendarix sandbox mode to send test events that do not count against production limits or affect real recipient addresses. This allows integration testing without generating fake suppression entries or polluting analytics.
What is the maximum number of events we can receive per second?
Sendarix delivers events in real time with no artificial rate limit on webhook delivery. During burst scenarios (e.g., a campaign delivery wave), your endpoint may receive hundreds of events per second. Design your endpoint to scale horizontally and your job queue to absorb these spikes. Monitor queue depth via the API to detect when processing falls behind.
Related Products
Start Receiving Email Events in Real Time
Configure your webhook endpoint in minutes. Get delivery, bounce, complaint, open, and click events as they happen.
