从黑盒到事件流
事件驱动的邮件运营
使用 Webhooks 同步产品状态、触发重试、告警团队并保持客户状态准确。
# 通过 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 — 保留集成并获得 control plane host: smtp.sendarix.com port: 587 (STARTTLS) username: "your_sending_key" header: X-Sendarix-Policy: transactional-critical
Webhook 能力
Webhooks 将邮件从黑盒变为产品可实时推理的事件流。
投递状态同步
随消息从已接受到已投递或已退信更新面向用户的状态。
失败自动化
在检测到临时或永久失败时触发重试路径与内部告警。
声誉保护
自动处理投诉与退信事件，将不良地址排除在未来发送之外。
工作流集成
将事件馈入 CRM、数据仓库、队列工作者与事件响应系统。
签名验证
验证入站 Webhook 签名，仅处理可信的 Sendarix 事件。
可安全重试的消费者
设计幂等处理程序，安全处理重复投递与延迟事件。
Webhook 生命周期
构建可靠事件驱动自动化的直接流程。
1. 发送消息
消息通过 API 或 SMTP 进入投递管道。
2. 生成事件
投递系统创建状态事件（已接受、已投递、已退信、已投诉）。
3. 投递 Webhook
事件 POST 到您的端点以供即时处理。
4. 应用响应
您的系统自动更新用户状态、触发任务或通知团队。
常见问题
Webhooks 能完全取代轮询吗？
对多数事件驱动工作流可以。团队仍使用分析做历史分析与报表。
应优先接入哪些事件？
从已投递、已退信、已投诉开始。再扩展到互动或自定义工作流事件。
Webhooks 仅适合大型系统吗？
不是。小型应用也能从即时状态同步与减少人工排障中受益。
如何验证 Webhook 请求真实？
使用共享密钥、签名或提供的 HMAC 头，校验时间戳防重放，在更新生产状态前拒绝未通过校验的负载。
Webhook 触发时我们的端点宕机怎么办？
依赖重试策略并使处理程序幂等。记录已收事件 ID，以免重试中的重复损坏数据库或用户通知。
应在 HTTP 请求中同步处理 Webhook 吗？
通常不应。快速确认，将工作入队到作业运行器并异步处理，以免慢任务导致超时与不必要的重试。
能否将同一事件扇出到多个内部服务？
可以，通过消息总线或路由器。保持单一入口验证并规范化负载，再分发到计费、CRM、数仓或告警消费者。
Webhooks 如何帮助退信与投诉处理？
可近乎实时更新抑制列表、暂停风险活动或标记账户，而非数小时后才通过工单发现问题。
预发与生产是否需要不同 Webhook URL？
强烈建议。隔离端点可防止测试事件触碰线上用户数据，并更易独立轮换凭据。
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.
相关产品
Start Receiving Email Events in Real Time
Configure your webhook endpoint in minutes. Get delivery, bounce, complaint, open, and click events as they happen.
