Monitor · Webhooks
Webhooks de e-mail
Pare de consultar painéis por atualizações de entrega. Envie eventos aceitos, entregues, com falha e de reclamação diretamente para sua aplicação e fluxos.
UI representativa do produto — dados ilustrativos, não métricas reais de clientes.
Da caixa-preta ao fluxo de eventos
Operações de e-mail orientadas a eventos
Use webhooks para sincronizar estado do produto, acionar novas tentativas, alertar equipes e manter o status do cliente preciso.
# Enviar email crítico por uma 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" });
# SMTP drop-in — mantenha sua integração e ganhe um control plane host: smtp.sendarix.com port: 587 (STARTTLS) username: "your_sending_key" header: X-Sendarix-Policy: transactional-critical
Capacidades de webhook
Webhooks transformam e-mail de caixa preta em fluxo de eventos que seu produto pode interpretar em tempo real.
Sincronização de estado de entrega
Atualize o status voltado ao usuário conforme as mensagens passam de aceitas a entregues ou com falha.
Automação de falhas
Acione caminhos de nova tentativa e alertas internos quando falhas transitórias ou permanentes forem detectadas.
Proteção de reputação
Trate eventos de reclamação e falha automaticamente para manter endereços ruins fora de envios futuros.
Integrações de fluxo de trabalho
Alimente eventos em CRM, data warehouse, workers de fila e sistemas de resposta a incidentes.
Verificação de assinatura
Valide assinaturas de webhook recebidas para processar apenas eventos Sendarix confiáveis.
Consumidores seguros para nova tentativa
Projete handlers idempotentes que processam com segurança entregas duplicadas e eventos atrasados.
Ciclo de vida do webhook
Um fluxo direto para construir automações orientadas a eventos confiáveis.
1. Enviar mensagem
A mensagem entra no pipeline de entrega via API ou SMTP.
2. Evento gerado
O sistema de entrega cria eventos de status (aceito, entregue, falha, reclamação).
3. Webhook entregue
Os eventos são enviados ao seu endpoint para processamento imediato.
4. App reage
Seus sistemas atualizam estado do usuário, disparam jobs ou notificam equipes automaticamente.
Perguntas frequentes
Webhooks podem substituir o polling completamente?
Para a maioria dos fluxos orientados a eventos, sim. Equipes ainda usam analytics para análise histórica e relatórios.
Quais eventos são mais importantes para começar?
Comece com entregue, falha e reclamação. Depois expanda para engajamento ou eventos de fluxo personalizado.
Webhooks são só para sistemas grandes?
Não. Até apps pequenos se beneficiam de sincronização imediata de estado e menos depuração manual de suporte.
Como verificar se as requisições de webhook são genuínas?
Use segredos compartilhados, assinaturas ou cabeçalhos HMAC onde disponíveis, valide timestamps para bloquear replays e rejeite payloads que falhem na verificação antes de atualizar o estado de produção.
E se nosso endpoint estiver fora quando o webhook disparar?
Confie em políticas de nova tentativa e torne handlers idempotentes. Registre IDs de eventos recebidos para que duplicatas de novas tentativas não corrompam o banco ou notificações.
O processamento do webhook deve ser síncrono na requisição HTTP?
Geralmente não. Reconheça rapidamente, enfileire trabalho em um executor de jobs e processe de forma assíncrona para que tarefas lentas não causem timeouts e novas tentativas desnecessárias.
Podemos distribuir o mesmo evento para vários serviços internos?
Sim, via barramento de mensagens ou roteador. Mantenha um único ponto de entrada que valida e normaliza payloads, depois distribua para billing, CRM, data warehouse ou alertas.
Como webhooks ajudam com falhas e reclamações?
Permitem atualizar listas de supressão, pausar campanhas arriscadas ou sinalizar contas quase em tempo real em vez de descobrir horas depois via chamados.
Precisamos de URLs de webhook separadas para staging e produção?
Altamente recomendado. Endpoints isolados impedem que eventos de teste toquem dados em produção e facilitam rotação independente de credenciais.
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.
Produtos relacionados
Start Receiving Email Events in Real Time
Configure your webhook endpoint in minutes. Get delivery, bounce, complaint, open, and click events as they happen.
