Pular para o conteúdo

Recursos

Webhooks

Receba callbacks HTTP em tempo real quando eventos acontecem no seu workspace.

Visão geral

O Notifuse trabalha com dois tipos de webhooks:

  1. 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.

  2. 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
Configurações, Webhooks: dois endpoints com os eventos e a taxa de sucesso das entregas

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:

Os tipos de evento de um endpoint de webhook, escolhidos por caixa de seleção, com a opção de selecionar todos

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

EventoDescrição
contact.createdUm novo contato foi adicionado ao workspace
contact.updatedOs dados do contato foram alterados
contact.deletedUm contato foi excluído definitivamente

Eventos de lista

EventoDescrição
list.subscribedO contato se inscreveu em uma lista
list.unsubscribedO contato cancelou a inscrição em uma lista
list.confirmedO contato confirmou a inscrição com confirmação dupla
list.resubscribedUm contato que tinha cancelado a inscrição se inscreveu de novo
list.bouncedO email para o contato teve retorno
list.complainedO contato marcou o email como spam
list.pendingA inscrição do contato aguarda confirmação
list.removedO contato foi removido da lista

Eventos de segmento

EventoDescrição
segment.joinedO contato entrou em um segmento (passou a atender aos critérios)
segment.leftO contato saiu de um segmento (não atende mais aos critérios)

Eventos de email

EventoDescrição
email.sentO email foi enviado ao contato
email.deliveredO servidor do destinatário confirmou a entrega do email
email.openedO contato abriu o email
email.clickedO contato clicou em um link do email
email.bouncedA entrega do email falhou
email.complainedO contato marcou o email como spam
email.unsubscribedO contato cancelou a inscrição pelo link do email

Eventos personalizados

EventoDescrição
custom_event.createdUm novo evento personalizado foi registrado
custom_event.updatedUm evento personalizado foi atualizado
custom_event.deletedUm 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_ids se aplica só aos eventos list.*, e segment_ids só aos eventos segment.*. 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:

CampoDescrição
enabledSe a assinatura está fazendo entregas no momento
sourceO que a criou. Ausente em uma assinatura criada por você; zapier em uma criada pela integração com o Zapier
consecutive_failuresTentativas de entrega que falharam em sequência. Volta a zero no primeiro sucesso
failing_sinceQuando começou a sequência atual de falhas. Apagado no primeiro sucesso
disabled_reasonPor que a assinatura foi desativada automaticamente. Ausente em uma que você mesmo desativou
last_delivery_atQuando 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
  }
}
CampoDescrição
idIdentificador único da entrega do webhook
typeO tipo de evento que disparou o webhook
timestampData e hora ISO 8601 em que o webhook foi enviado
workspace_idO workspace onde o evento aconteceu
dataOs 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çalhoDescrição
webhook-idIdentificador único da entrega do webhook
webhook-timestampTimestamp Unix do momento em que o webhook foi enviado
webhook-signatureAssinatura HMAC-SHA256 do payload

Verificar a assinatura

  1. Extraia o timestamp e a assinatura dos cabeçalhos
  2. Monte o payload assinado: {webhook-id}.{webhook-timestamp}.{body}
  3. Calcule o HMAC-SHA256 com o segredo do seu webhook
  4. 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:

TentativaIntervalo após a anterior
1Imediata
230 segundos
31 minuto
42 minutos
55 minutos
615 minutos
730 minutos
81 hora
92 horas
106 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 Requests nunca 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. O 404 nã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.regenerateSecret para trocar o segredo de assinatura
  • Veja a Referência da API para a documentação completa dos endpoints