Visão geral
O Notifuse trabalha com dois tipos de webhooks:
-
Webhooks de entrada: callbacks dos provedores de email (Amazon SES, Mailgun, Postmark etc.) que informam o Notifuse sobre retornos, reclamações, entregas e outros eventos de email. Eles são configurados automaticamente quando você configura uma integração de email.
-
Webhooks de saída: callbacks HTTP que o Notifuse envia para o seu servidor quando eventos acontecem. Esta página trata deles.
Um webhook de saída envia uma requisição HTTP POST para o seu servidor quando um evento específico acontece no Notifuse. Use-os para:
- Sincronizar os dados dos contatos com o seu CRM ou outros sistemas
- Disparar fluxos em ferramentas de automação externas
- Criar integrações e dashboards sob medida
- Reagir em tempo real a eventos de engajamento com os emails
Criar uma assinatura de webhook
Crie uma assinatura de webhook no console, em Configurações → Webhooks → Adicionar endpoint, onde você escolhe a URL e os tipos de evento:
Ou crie pela API:
curl -X POST "https://your-instance.com/api/webhookSubscriptions.create" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"workspace_id": "your_workspace",
"name": "Production Webhook",
"url": "https://api.example.com/webhooks/notifuse",
"event_types": ["contact.created", "contact.updated", "email.sent"]
}'
Tipos de evento disponíveis
Eventos de contato
| Evento | Descrição |
|---|---|
contact.created | Um novo contato foi adicionado ao workspace |
contact.updated | Os dados do contato foram alterados |
contact.deleted | Um contato foi excluído definitivamente |
Eventos de lista
| Evento | Descrição |
|---|---|
list.subscribed | O contato se inscreveu em uma lista |
list.unsubscribed | O contato cancelou a inscrição em uma lista |
list.confirmed | O contato confirmou a inscrição com confirmação dupla |
list.resubscribed | Um contato que tinha cancelado a inscrição se inscreveu de novo |
list.bounced | O email para o contato teve retorno |
list.complained | O contato marcou o email como spam |
list.pending | A inscrição do contato aguarda confirmação |
list.removed | O contato foi removido da lista |
Eventos de segmento
| Evento | Descrição |
|---|---|
segment.joined | O contato entrou em um segmento (passou a atender aos critérios) |
segment.left | O contato saiu de um segmento (não atende mais aos critérios) |
Eventos de email
| Evento | Descrição |
|---|---|
email.sent | O email foi enviado ao contato |
email.delivered | O servidor do destinatário confirmou a entrega do email |
email.opened | O contato abriu o email |
email.clicked | O contato clicou em um link do email |
email.bounced | A entrega do email falhou |
email.complained | O contato marcou o email como spam |
email.unsubscribed | O contato cancelou a inscrição pelo link do email |
Eventos personalizados
| Evento | Descrição |
|---|---|
custom_event.created | Um novo evento personalizado foi registrado |
custom_event.updated | Um evento personalizado foi atualizado |
custom_event.deleted | Um evento personalizado passou por exclusão lógica |
Filtros de eventos personalizados
Para eventos personalizados, você pode filtrar, se quiser, por goal_types e event_names:
{
"event_types": ["custom_event.created"],
"custom_event_filters": {
"goal_types": ["purchase", "subscription"],
"event_names": ["orders/fulfilled", "payment.succeeded"]
}
}
Filtrar por lista e segmento
Por padrão, uma assinatura de eventos list.* recebe um evento para todas as listas do workspace, e uma de eventos segment.*, para todos os segmentos. Restrinja com list_ids e segment_ids:
{
"event_types": ["list.subscribed", "list.unsubscribed", "segment.joined"],
"list_ids": ["newsletter", "product_updates"],
"segment_ids": ["vip_customers"]
}
list_idsse aplica só aos eventoslist.*, esegment_idssó aos eventossegment.*. Nenhum dos dois afeta os tipos de evento de contato, de email ou personalizados.- Omitir um filtro, ou enviar um array vazio, significa “todas as listas” ou “todos os segmentos”. As assinaturas criadas antes desses filtros existirem continuam funcionando assim.
- Os dois filtros podem ser alterados depois com
webhookSubscriptions.update.
Filtre sempre que puder. Um workspace com listas grandes gera uma entrega por contato a cada evento de lista, então uma assinatura que precisa de uma lista, mas recebe todas, faz a sua instância trabalhar para eventos que serão descartados.
Campos da assinatura
Além do nome, da URL e dos tipos de evento, uma assinatura informa:
| Campo | Descrição |
|---|---|
enabled | Se a assinatura está fazendo entregas no momento |
source | O que a criou. Ausente em uma assinatura criada por você; zapier em uma criada pela integração com o Zapier |
consecutive_failures | Tentativas de entrega que falharam em sequência. Volta a zero no primeiro sucesso |
failing_since | Quando começou a sequência atual de falhas. Apagado no primeiro sucesso |
disabled_reason | Por que a assinatura foi desativada automaticamente. Ausente em uma que você mesmo desativou |
last_delivery_at | Quando foi a última entrega bem-sucedida |
Atenção
Uma assinatura com source foi criada por outra ferramenta, que é a dona dela. Excluir pelo Notifuse uma assinatura criada pelo Zapier quebra sem aviso o Zap por trás dela, e o Zap não a recria sozinho. Em vez disso, desligue o Zap no Zapier.
Quando o Notifuse desativa uma assinatura
O Notifuse só aposenta um endpoint que parou de responder quando as duas condições são atendidas: 20 falhas seguidas e uma sequência de falhas que dura mais de duas horas. Uma indisponibilidade curta (um deploy, um reinício, um receptor fora do ar por alguns instantes durante uma importação) nunca desativa a sua assinatura, por mais entregas que ele recuse nesse meio-tempo. Essas entregas são tentadas de novo com o backoff habitual.
A exceção é um endpoint que responde 410 Gone: ele é aposentado na hora, porque esse status significa que o receptor diz que a assinatura não existe mais.
Reativar uma assinatura apaga o histórico de falhas dela, então a próxima falha não a aposenta de novo.
Para onde o Notifuse pode entregar
O seu endpoint precisa ser acessível pela internet pública. O Notifuse se recusa a se conectar a endereços privados, de loopback, link-local e reservados, incluindo o endpoint de metadados da instância na nuvem. Ele verifica de novo a cada redirecionamento, então uma URL pública que redireciona para uma interna também é recusada. Uma assinatura cuja URL aponta para um desses endereços é rejeitada quando você a salva.
Nota
Só na auto-hospedagem: para entregar webhooks de propósito a um serviço da sua própria rede privada (um contêiner na mesma rede Docker, uma ferramenta de automação interna), defina WEBHOOK_DELIVERY_ALLOW_PRIVATE_HOSTS=true. Deixe essa variável sem valor em qualquer implantação onde alguém em quem você não confiaria com a sua rede interna possa criar assinaturas ou editar automações. A mesma configuração vale para os nós de webhook das automações.
Uma entrega recusada dessa forma é tentada de novo como qualquer outra falha, mas nunca conta para a desativação da assinatura, então basta corrigir a URL ou a configuração para que as entregas voltem.
Estrutura do payload
Todos os payloads de webhook seguem esta estrutura:
{
"id": "delivery_abc123",
"type": "contact.created",
"timestamp": "2024-01-15T10:30:00Z",
"workspace_id": "ws_1234567890",
"data": {
// Event-specific data
}
}
| Campo | Descrição |
|---|---|
id | Identificador único da entrega do webhook |
type | O tipo de evento que disparou o webhook |
timestamp | Data e hora ISO 8601 em que o webhook foi enviado |
workspace_id | O workspace onde o evento aconteceu |
data | Os dados próprios do evento |
Exemplo: contato criado
{
"id": "delivery_abc123",
"type": "contact.created",
"timestamp": "2024-01-15T10:30:00Z",
"workspace_id": "ws_1234567890",
"data": {
"email": "user@example.com",
"id": "contact_12345",
"external_id": "ext_67890",
"first_name": "John",
"last_name": "Doe",
"tags": ["newsletter", "customer"],
"tracking_opens_consent": "granted",
"tracking_clicks_consent": null,
"tracking_consent_updated_at": "2024-01-15T10:30:00Z",
"tracking_consent_source": "api",
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:30:00Z"
}
}
Exemplo: email enviado
{
"id": "delivery_def456",
"type": "email.sent",
"timestamp": "2024-01-15T10:30:00Z",
"workspace_id": "ws_1234567890",
"data": {
"message_id": "msg_xyz789",
"email": "user@example.com",
"subject": "Welcome to our newsletter",
"broadcast_id": "bc_abc123",
"template_id": "welcome_email",
"created_at": "2024-01-15T10:30:00Z"
}
}
Exemplo: email aberto
{
"id": "delivery_ghi789",
"type": "email.opened",
"timestamp": "2024-01-15T11:45:00Z",
"workspace_id": "ws_1234567890",
"data": {
"message_id": "msg_xyz789",
"email": "user@example.com",
"subject": "Welcome to our newsletter",
"broadcast_id": "bc_abc123",
"template_id": "welcome_email",
"created_at": "2024-01-15T11:45:00Z"
}
}
Exemplo: entrada em segmento
{
"id": "delivery_jkl012",
"type": "segment.joined",
"timestamp": "2024-01-15T10:30:00Z",
"workspace_id": "ws_1234567890",
"data": {
"email": "user@example.com",
"contact_id": "contact_12345",
"segment_id": "seg_vip_customers",
"segment_name": "VIP Customers",
"created_at": "2024-01-15T10:30:00Z"
}
}
Verificar as assinaturas dos webhooks
O Notifuse assina todos os payloads de webhook seguindo a especificação Standard Webhooks, com HMAC-SHA256.
Cabeçalhos
Cada requisição de webhook inclui estes cabeçalhos:
| Cabeçalho | Descrição |
|---|---|
webhook-id | Identificador único da entrega do webhook |
webhook-timestamp | Timestamp Unix do momento em que o webhook foi enviado |
webhook-signature | Assinatura HMAC-SHA256 do payload |
Verificar a assinatura
- Extraia o timestamp e a assinatura dos cabeçalhos
- Monte o payload assinado:
{webhook-id}.{webhook-timestamp}.{body} - Calcule o HMAC-SHA256 com o segredo do seu webhook
- Compare com a assinatura recebida
Exemplos de código
const crypto = require('crypto');
function verifyWebhook(payload, headers, secret) {
const msgId = headers['webhook-id'];
const msgTimestamp = headers['webhook-timestamp'];
const msgSignature = headers['webhook-signature'];
// Check timestamp is within 5 minutes
const now = Math.floor(Date.now() / 1000);
if (Math.abs(now - parseInt(msgTimestamp)) > 300) {
throw new Error('Timestamp too old');
}
// Construct signed payload
const signedPayload = `${msgId}.${msgTimestamp}.${payload}`;
// Compute signature
const secretBytes = Buffer.from(secret.replace('whsec_', ''), 'base64');
const expectedSignature = crypto
.createHmac('sha256', secretBytes)
.update(signedPayload)
.digest('base64');
// Extract v1 signature
const signatures = msgSignature.split(' ');
for (const sig of signatures) {
const [version, signature] = sig.split(',');
if (version === 'v1' && signature === expectedSignature) {
return true;
}
}
throw new Error('Invalid signature');
}import hmac
import hashlib
import base64
import time
def verify_webhook(payload: str, headers: dict, secret: str) -> bool:
msg_id = headers.get('webhook-id')
msg_timestamp = headers.get('webhook-timestamp')
msg_signature = headers.get('webhook-signature')
# Check timestamp is within 5 minutes
now = int(time.time())
if abs(now - int(msg_timestamp)) > 300:
raise ValueError('Timestamp too old')
# Construct signed payload
signed_payload = f"{msg_id}.{msg_timestamp}.{payload}"
# Compute signature
secret_bytes = base64.b64decode(secret.replace('whsec_', ''))
expected_signature = base64.b64encode(
hmac.new(secret_bytes, signed_payload.encode(), hashlib.sha256).digest()
).decode()
# Extract v1 signature
for sig in msg_signature.split(' '):
version, signature = sig.split(',')
if version == 'v1' and signature == expected_signature:
return True
raise ValueError('Invalid signature')package main
import (
"crypto/hmac"
"crypto/sha256"
"encoding/base64"
"errors"
"fmt"
"math"
"strconv"
"strings"
"time"
)
func VerifyWebhook(payload string, headers map[string]string, secret string) error {
msgID := headers["webhook-id"]
msgTimestamp := headers["webhook-timestamp"]
msgSignature := headers["webhook-signature"]
// Check timestamp is within 5 minutes
ts, _ := strconv.ParseInt(msgTimestamp, 10, 64)
now := time.Now().Unix()
if math.Abs(float64(now-ts)) > 300 {
return errors.New("timestamp too old")
}
// Construct signed payload
signedPayload := fmt.Sprintf("%s.%s.%s", msgID, msgTimestamp, payload)
// Compute signature
secretBytes, _ := base64.StdEncoding.DecodeString(strings.TrimPrefix(secret, "whsec_"))
h := hmac.New(sha256.New, secretBytes)
h.Write([]byte(signedPayload))
expectedSig := base64.StdEncoding.EncodeToString(h.Sum(nil))
// Extract v1 signature
for _, sig := range strings.Split(msgSignature, " ") {
parts := strings.SplitN(sig, ",", 2)
if len(parts) == 2 && parts[0] == "v1" && parts[1] == expectedSig {
return nil
}
}
return errors.New("invalid signature")
}<?php
function verifyWebhook(string $payload, array $headers, string $secret): bool {
$msgId = $headers['webhook-id'] ?? '';
$msgTimestamp = $headers['webhook-timestamp'] ?? '';
$msgSignature = $headers['webhook-signature'] ?? '';
// Check timestamp is within 5 minutes
$now = time();
if (abs($now - (int)$msgTimestamp) > 300) {
throw new Exception('Timestamp too old');
}
// Construct signed payload
$signedPayload = "{$msgId}.{$msgTimestamp}.{$payload}";
// Compute signature
$secretBytes = base64_decode(str_replace('whsec_', '', $secret));
$expectedSignature = base64_encode(
hash_hmac('sha256', $signedPayload, $secretBytes, true)
);
// Extract v1 signature
foreach (explode(' ', $msgSignature) as $sig) {
[$version, $signature] = explode(',', $sig, 2);
if ($version === 'v1' && $signature === $expectedSignature) {
return true;
}
}
throw new Exception('Invalid signature');
}Comportamento das novas tentativas
O Notifuse tenta de novo as entregas com falha usando backoff exponencial.
Calendário das tentativas
Uma entrega tem até 10 tentativas, a última cerca de 10 horas depois da primeira:
| Tentativa | Intervalo após a anterior |
|---|---|
| 1 | Imediata |
| 2 | 30 segundos |
| 3 | 1 minuto |
| 4 | 2 minutos |
| 5 | 5 minutos |
| 6 | 15 minutos |
| 7 | 30 minutos |
| 8 | 1 hora |
| 9 | 2 horas |
| 10 | 6 horas |
Se a 10ª tentativa também falhar, a entrega é marcada como falha e não é tentada de novo.
Critério de sucesso
Uma entrega é bem-sucedida quando o seu endpoint retorna um código de status HTTP 2xx (200-299).
Condições de falha
Uma tentativa de entrega falha se:
- O seu endpoint retorna um código de status diferente de 2xx
- O seu endpoint leva mais de 10 segundos para responder
- O endpoint está inacessível (erro de DNS, conexão recusada etc.)
Desativação automática
Um endpoint que mudou de endereço, foi desativado ou perdeu o registro DNS não volta sozinho, e o Notifuse não guarda entregas na fila para ele para sempre.
Depois de uma longa sequência de falhas seguidas, o Notifuse desativa a assinatura e registra nela o motivo, para que você a diferencie de uma que você mesmo desativou. O contador é por assinatura, e uma única entrega bem-sucedida o zera, então só um endpoint que falha de forma persistente é desativado.
Duas respostas recebem um tratamento especial:
429 Too Many Requestsnunca conta como falha. Ela significa que o seu servidor está pedindo menos requisições, e um workspace movimentado a ponto de ser limitado não deve perder a integração por isso. A entrega é tentada de novo no calendário normal.410 Goneé definitivo já na primeira resposta. É a forma padrão de um receptor dizer “esta assinatura morreu, pare de enviar”, então a assinatura é aposentada na hora, sem a sequência de falhas habitual. Uma assinatura criada por você é desativada com esse motivo registrado; uma criada por outra ferramenta, como o Zapier, é removida de vez, porque a ferramenta a recria quando precisar. O404não recebe esse tratamento: um endpoint que some por pouco tempo é tentado de novo como qualquer outra falha.
Para trazer de volta uma assinatura desativada, corrija o endpoint e reative a assinatura.
Nota
Uma assinatura desativada descarta os eventos em vez de guardá-los na fila. As entregas previstas enquanto ela está desligada, seja você ou o Notifuse quem a desligou, ficam marcadas como falha no log de entregas e não são reenviadas quando você a religa. Para recuperar os eventos de uma indisponibilidade, leia-os pela API.
Excluir uma assinatura
Excluir uma assinatura também descarta as entregas que ainda estavam na fila para ela, então não sobra nada para tentar de novo nem uma fila para esvaziar antes.
Se você pretende trazer o endpoint de volta, desative a assinatura em vez de excluí-la: a desativação é reversível e mantém a assinatura com o segredo de assinatura e o histórico de entregas. Uma assinatura excluída não pode ser restaurada, e recriá-la gera um novo segredo de assinatura.
Boas práticas
Retorne 2xx rapidamente
Retorne uma resposta de sucesso o mais rápido possível e, se necessário, processe o payload de forma assíncrona:
// Good: Acknowledge quickly, process later
app.post('/webhooks/notifuse', async (req, res) => {
// Quickly validate signature
verifyWebhook(req.body, req.headers, SECRET);
// Queue for async processing
await queue.add('process-webhook', req.body);
// Respond immediately
res.status(200).json({ received: true });
});
Trate entregas duplicadas
Em casos raros, um webhook é entregue mais de uma vez. Use o cabeçalho webhook-id para garantir a idempotência:
app.post('/webhooks/notifuse', async (req, res) => {
const webhookId = req.headers['webhook-id'];
// Check if we've already processed this webhook
if (await hasProcessed(webhookId)) {
return res.status(200).json({ received: true, duplicate: true });
}
// Mark as processed before handling
await markProcessed(webhookId);
// Process the webhook
await processWebhook(req.body);
res.status(200).json({ received: true });
});
Verifique as assinaturas
Sempre verifique as assinaturas dos webhooks em produção, para ter certeza de que as requisições vêm do Notifuse.
Acompanhe as falhas de entrega
No console, Configurações → Webhooks mostra a taxa de sucesso de cada assinatura nos últimos 7 dias e a última entrega bem-sucedida. Abra uma assinatura para ver as entregas bem-sucedidas e com falha das últimas 24 horas ou dos últimos 7 dias, e escolha Ver entregas para listá-las nos logs.
Pela API, adicione status (pending, delivering, delivered ou failed) para listar só as entregas nesse status; qualquer outro valor retorna 400. failed também inclui as entregas que aguardam uma nova tentativa, que voltam para delivering quando são reenviadas, então uma entrega listada como falha ainda pode ter sucesso:
curl "https://your-instance.com/api/webhookSubscriptions.deliveries?workspace_id=ws_123&subscription_id=whsub_456&status=failed" \
-H "Authorization: Bearer YOUR_API_KEY"
Testar webhooks
Enviar um webhook de teste
Use o endpoint de teste para verificar a configuração do seu webhook:
curl -X POST "https://your-instance.com/api/webhookSubscriptions.test" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"workspace_id": "your_workspace",
"id": "whsub_a1b2c3d4e5f6",
"event_type": "contact.created"
}'
O parâmetro opcional event_type faz o teste enviar um payload de exemplo realista para esse tipo de evento. Sem ele, o teste envia um payload genérico.
Desenvolvimento local
No desenvolvimento local, use ferramentas como ngrok ou localtunnel para expor o seu servidor local:
# Start ngrok
ngrok http 3000
# Use the ngrok URL as your webhook endpoint
# https://abc123.ngrok.io/webhooks/notifuse
Permissões
As assinaturas de saída seguem a permissão Assinaturas de Webhook. Com Leitura, o membro lista as assinaturas, abre cada uma e vê o histórico de entregas, incluindo o payload de cada evento e o status e o corpo da resposta do endpoint. Com Escrita, ele cria, atualiza, exclui, ativa e desativa assinaturas, e dispara uma entrega de teste, que conta como escrita porque faz o seu servidor ser chamado.
Os callbacks recebidos dos provedores seguem a permissão Eventos de Webhook. Com Leitura, o membro vê os callbacks brutos que os seus provedores de email enviaram ao Notifuse, incluindo os endereços dos destinatários e os diagnósticos dos provedores. A escrita em Eventos de Webhook não controla nada hoje: as linhas chegam pelas rotas de callback dos provedores, que não têm sessão e não verificam nenhuma permissão, então concedê-la não dá acesso a nada. O console a mostra concedida e bloqueada.
O catálogo de tipos de evento disponíveis não exige nenhuma permissão: qualquer membro ou chave autenticada pode listá-lo.
Duas ações ficam reservadas ao proprietário do workspace, sejam quais forem as permissões de um membro ou de uma chave API:
- Regenerar o segredo de assinatura de uma assinatura de webhook. O segredo também fica oculto para todos, menos para o proprietário, então a leitura em Assinaturas de Webhook nunca o expõe: um membro pode listar as assinaturas e inspecionar as entregas sem nunca ver a chave que assina esses payloads.
- Registrar webhooks em um provedor de email, porque isso usa as credenciais do provedor guardadas na sua integração.
Atenção
A permissão de Escrita em Assinaturas de Webhook vai além do que o nome sugere. Uma assinatura escolhe os eventos que recebe, então quem tem essa permissão pode assinar eventos de contato e de email e receber esses dados em uma URL de sua escolha. Conceda-a como concederia o acesso de leitura aos contatos e ao histórico de mensagens por trás desses eventos.
Observações
- Os webhooks exigem endpoints HTTPS em produção
- O segredo de assinatura é gerado automaticamente quando você cria uma assinatura
- Use
webhookSubscriptions.regenerateSecretpara trocar o segredo de assinatura - Veja a Referência da API para a documentação completa dos endpoints
