Webhooks e eventos
Os webhooks da conta enviam o que acontece em toda a sua conta para uma URL que você escolhe, na hora: um lead novo, uma reunião agendada, um negócio mudando de etapa. São eles que as integrações com Zapier e n8n usam por baixo, e você também pode apontá-los para o seu próprio endpoint. Se você só usa o Zapier, não precisa adicionar um webhook por conta própria: o cartão Zapier na página Desenvolvedores começa um Zap a partir de um modelo, e o Zap cria o próprio webhook.
Eles se somam ao webhook do projeto da página Respostas de um e-mail, que continua funcionando como antes. Um webhook do projeto cobre as interações de um único e-mail. Um webhook da conta cobre todos os e-mails, mais os eventos abaixo, e é assinado do mesmo jeito.
Adicionar um webhook
- Vá em Desenvolvedores no painel e encontre o cartão Webhooks.
- Informe a URL do endpoint (uma URL
https://pública) e marque os Eventos que quiser. - Clique em Adicionar webhook e copie o segredo de assinatura. Ele só aparece desta vez.
Cada webhook mostra como foi criado (Painel, API, Zapier ou n8n), o status e a última entrega. Enviar teste envia um exemplo do evento escolhido, com "test": true no data. Excluir remove o webhook. Uma conta pode ter até 50.
Só o dono da conta pode adicionar ou excluir webhooks, e talvez seja preciso entrar de novo antes.
Eventos
| Evento | Dispara quando |
|---|---|
interaction.received | Um destinatário interage com um e-mail: um voto, uma avaliação, uma resposta de quiz, um clique rastreado, uma compra e assim por diante. Repetições deduplicadas não disparam. |
form.submitted | Um formulário dentro de um e-mail é enviado (source: "email-form"), ou um formulário de inscrição (source: "signup-form"). |
contact.created | Um contato é adicionado a uma lista. |
contact.updated | Os campos de um contato mudam. Salvar dados idênticos não dispara. |
lead.hot | A pontuação de engajamento de um contato cruza, subindo, o seu limite de lead quente. |
lead.new | Um lead novo chega por um formulário de inscrição ou por um formulário dentro de um e-mail. |
booking.created | Uma reunião é agendada. |
booking.cancelled | Um agendamento é cancelado, com cancelledBy. Remarcar não dispara nenhum dos dois eventos de agendamento. |
deal.created | Um negócio é criado, de qualquer origem: o quadro, uma regra automática, uma jornada, uma proposta ou a API. |
deal.stage_changed | Um negócio muda de etapa, incluindo ganho e perdido. |
purchase.completed | Um destinatário paga por um checkout dentro do e-mail. |
journey.completed | Um contato chega ao fim de uma jornada. Quem sai antes não conta. |
experiment.decided | Alguém registra a decisão de um experimento: uma vencedora, sem diferença ou inconclusivo. |
experiment.completed | Os resultados finais de um experimento ficam prontos: a análise que cobre toda a janela de observação foi executada. |
response.completed | Um destinatário respondeu a todos os blocos que um e-mail conta, por exemplo cada pergunta de uma pesquisa. Uma vez por destinatário e e-mail. |
review.submitted | Um destinatário enviou uma avaliação de um bloco Pedido de avaliação. Dispara uma vez por avaliação. |
Os eventos de contato disparam com importações, formulários de inscrição, a API, sincronizações e conectores de IA. Uma única gravação de mais de 500 contatos (uma importação CSV grande, por exemplo) não dispara nenhum, para que uma importação não inicie milhares de fluxos. Um contato adicionado na grade de contatos, digitado ou mesclado de um CSV, dispara contact.created. Edições em contatos existentes na grade não disparam contact.updated, nem as etapas de jornada Atualizar campo ou as respostas salvas.
lead.hot e lead.new disparam independentemente dos interruptores e limites dos seus alertas de leads: assinar já é o consentimento.
Os dois eventos de experimento carregam {experiment}, o mesmo formato que a API de experimentos devolve. Ele traz as variantes, o result mais recente da análise, a decision registrada com a evidence que a análise atribuiu a ela e uma resultsUrl. experiment.completed dispara uma vez por experimento, mesmo quando a decisão foi registrada antes do fim em um teste sequencial. Em um experimento dentro de uma jornada, a vencedora indica um caminho: decision.pathIndex.
response.completed traz o e-mail (projectId, projectName), a chave recipient e o seu contact, o sendId e o variant quando um envio o enviou (senão null), os blockIds contados e, em answers, a resposta de cada bloco, o mesmo valor que interaction.received traz em event.value, com firstAnsweredAt e completedAt. Um e-mail conta cada enquete, avaliação, quiz, RSVP e formulário que o destinatário vê, a menos que o painel Respostas do Estúdio escolha menos, e com menos de dois nunca dispara. Mudar uma resposta depois não o dispara de novo, e uma visualização sem destinatário (uma prévia, um link genérico) nunca se completa.
review.submitted leva o e-mail (projectId, projectName), o blockId, o que foi avaliado em subject (kind, id, title), a rating, o title e o body, o displayName escolhido, verifiedPurchase, o contact e o recipient, e submittedAt.
Payload
Toda entrega é um POST JSON com o mesmo envelope:
{
"id": "evt_8c1f…",
"type": "deal.stage_changed",
"createdAt": 1790000000000,
"data": {
"deal": {
"id": "deal_abc123",
"title": "Annual plan",
"value": 1200,
"currency": "USD",
"pipelineId": "owner_default",
"stageId": "proposal-sent",
"stage": "Proposal sent",
"status": "open",
"source": "manual",
"listId": "list_abc123",
"rowId": "3f6c1b0e2d…",
"email": "[email protected]"
},
"fromStageId": "meeting-booked"
}
}
id é o mesmo em cada entrega de um mesmo evento e também vai no cabeçalho X-MailInApp-Idempotency-Key, então você pode descartar com segurança uma reentrega que já processou. createdAt está em milissegundos epoch.
Para ver o data de cada tipo de evento, chame GET /api/v1/events/sample ou use Enviar teste.
Verificar a assinatura
As entregas trazem os cabeçalhos X-MailInApp-Timestamp e X-MailInApp-Signature, calculados exatamente como no webhook do projeto. Verifique-os sobre o corpo bruto com o seu segredo de assinatura e rejeite timestamps de mais de alguns minutos atrás. A documentação do webhook do projeto traz uma função Node.js pronta.
Novas tentativas
O seu endpoint tem 5 segundos para responder com um 2xx. Qualquer outra coisa (tempo esgotado, status de erro, redirecionamento) é uma falha, e a entrega é tentada de novo automaticamente, com intervalos crescentes ao longo de várias horas, com o mesmo corpo e a mesma chave de idempotência, para a URL atual do webhook. Responda rápido e faça o trabalho demorado depois.
- Se o seu endpoint responder
410 Gone, o webhook é desativado. É assim que clientes REST Hooks cancelam a assinatura. - Revogar uma chave de API desativa os webhooks criados com ela.
- Excluir um webhook interrompe as novas tentativas pendentes.
Assinar pela API
Zapier, n8n e o seu próprio código podem gerenciar webhooks com uma chave de API (Authorization: Bearer mia_live_…):
curl https://mailinapp.com/api/v1/webhooks \
-H "Authorization: Bearer mia_live_..." \
-H "Content-Type: application/json" \
-d '{"url": "https://hooks.example.com/mailinapp", "events": ["lead.hot", "booking.created"]}'
A resposta 201 traz o id da assinatura e o secret dela, que assina cada entrega. Guarde-o: ele não é devolvido de novo. GET /api/v1/webhooks lista as suas assinaturas, e DELETE /api/v1/webhooks/{id} remove uma. Um único nome de evento desconhecido faz a requisição inteira ser recusada. Essas rotas aceitam 30 requisições por minuto por chave.
O contrato completo está na especificação OpenAPI.
Ler resultados de experimentos
Com uma chave de API, o seu código pode ler os seus experimentos, por exemplo para buscar os números assim que experiment.completed chegar:
GET /api/v1/experimentslista os experimentos, dos mais recentes para os mais antigos. Filtre porstatus,kind(sendoujourney),projectIdoujourneyId.GET /api/v1/experiments/{id}devolve um experimento.GET /api/v1/experiments/{id}/resultsdevolve o experimento com o relatório completo: os mesmos números da exportação em JSON da página de resultados, só agregados.
Essas rotas apenas leem. Bloquear, iniciar, decidir e implantar uma vencedora continuam no painel. Elas aceitam 60 requisições por minuto por chave. Como ler os resultados de um experimento explica o que os números significam.