Webhooks
Receba uma chamada assinada no seu servidor quando chega uma resposta, alguém demonstra interesse, um e-mail dá bounce ou uma lista ou exportação fica pronta. Incluído a partir do plano Pro.
Eventos
| Evento | Quando é disparado | O que data contém |
|---|---|---|
reply.received | Uma pessoa respondeu a uma das suas campanhas. Avisos automáticos de ausência ficam de fora, a menos que o seu workspace tenha ocultado o rótulo Fora do escritório. Também é disparado quando você move uma resposta de Fora do escritório para outro rótulo | classification, lead_email, campaign_id, subject, snippet, reply_id, lead_id, received_at |
reply.positive | Você deu a uma resposta o rótulo Interessado ou Pedido de reunião, no app ou com POST /api/v1/inbox/{id}/classify. Só é disparado quando o rótulo muda, então uma resposta envia reply.received quando chega e reply.positive quando você a rotula | classification, lead_email, campaign_id, subject, snippet, reply_id, lead_id, received_at |
email.bounced | Um e-mail de campanha deu bounce. Não é enviado quando essa pessoa já tinha respondido antes | lead_email, campaign_id, subject |
email.unsubscribed | Alguém usou o link de descadastro, ou você deu à resposta dessa pessoa o rótulo Descadastrar | classification, lead_email, campaign_id, subject, snippet, e source para o link de descadastro, ou reply_id, lead_id e received_at quando veio de um rótulo |
campaign.paused | O Argorant pausou uma campanha em andamento: os e-mails de campanha do seu plano acabaram (ou o teste ou o plano terminou), ou a campanha se pausou sozinha por causa de bounces ou de caixas de e-mail offline. Uma pausa feita por você não envia nada | campaign_id, campaign_name, reason, message, e campaign_emails (plano) ou metrics e url (pausa automática) |
campaign.resumed | Há e-mails de campanha disponíveis de novo (um novo mês ou um plano maior), então uma campanha pausada pelo plano volta a enviar. Um início feito por você não envia nada | campaign_id, campaign_name, reason, message, campaign_emails |
export.ready | Uma exportação terminou. Não é enviado quando ela falhou | job_id, status, total_rows, verified_rows, status_url, download_url, status_api_path, download_api_path |
list.ready | Uma lista terminou de ser preenchida, também depois que você adicionou mais pessoas. Não é enviado quando o preenchimento falhou | list_id, list_name, job_id, status, total_items, note, status_url, status_api_path |
verification.completed | Uma verificação de um único e-mail com uma chave de API terminou | email, status, deliverable, is_role_based, is_free, is_disposable |
segment.new_matches | Uma lista de busca salva tem mais pessoas correspondentes do que na última contagem. As listas são verificadas a cada 30 minutos, mais ou menos | list_id, list_name, previous_total, current_total, new_matches |
lead.created | Pessoas foram adicionadas a uma campanha, no app, pela API, a partir de um arquivo, de uma lista ou por uma movimentação. Uma entrega por lote que a campanha recebeu, então uma importação grande chega em várias entregas. Pessoas removidas de novo antes de a entrega sair ficam de fora | campaign_id, campaign_name, count, leads, cada um com lead_id, email, first_name, last_name, company, title, status, custom_fields, added_at |
campaign.status_changed | O status de uma campanha mudou, por você ou pelo Argorant: um início, pausa, parada ou arquivamento, ou uma pausa por e-mails de campanha, bounces ou caixas de e-mail offline. Também é disparado junto com campaign.paused e campaign.resumed | campaign_id, campaign_name, from, to, changed_at |
email.sent | E-mails de campanha saíram. Chega em cerca de um minuto após o envio, uma entrega por campanha com até 100 e-mails | campaign_id, campaign_name, count, emails, cada um com email_id, lead_id, lead_email, subject, step, mailbox, sent_at |
reply.label_changed | Alguém definiu ou mudou o rótulo de uma resposta, na caixa de entrada do app ou com POST /api/v1/inbox/{id}/classify. Definir o mesmo rótulo de novo não envia nada | reply_id, lead_id, lead_email, campaign_id, subject, from, to, changed_at |
Os eventos de campanha vão para os webhooks do proprietário do workspace e de cada membro ativo da equipe, então cada pessoa pode direcioná-los para as próprias ferramentas. Exportações, listas e verificações vão para os webhooks da pessoa que as iniciou. Novas correspondências vão para os webhooks do dono da lista.
Nos eventos de resposta, classification é null para uma resposta que acabou de chegar, e é a chave do rótulo depois que alguém definiu um, por exemplo positive ou meeting_request. subject contém até 300 caracteres e snippet até 500 caracteres de texto simples. reply_id é a resposta, lead_id a pessoa na campanha e received_at o momento em que a resposta chegou. O reason de campaign.paused é campaign_email_allowance quando o plano pausou a campanha, e auto_pause_bounce_rate, auto_pause_inboxes_offline ou auto_pause quando ela se pausou sozinha. campaign_emails.reason diz por que os e-mails acabaram (allowance_used, trial_ended, plan_ended ou confirm_email) e fica vazio em campaign.resumed.
from e to de campaign.status_changed são draft, active, paused, completed ou archived. Em reply.label_changed são chaves de rótulo, e from é null quando a resposta não tinha rótulo. lead.created, campaign.status_changed e email.sent começam cerca de um minuto depois que o primeiro webhook que os quer é criado; nada de antes é enviado. Quando o seu servidor fica muito para trás, novas chamadas email.sent esperam até ele se atualizar; nenhuma é descartada.
Se em vez disso você consulta a API em intervalos fixos, comece cada leitura alguns minutos antes do fim da anterior e pule os ids que você já tem. Uma linha pode ser salva um instante depois do horário que ela traz, então uma janela que começa exatamente onde a última terminou pode perdê-la. Com webhooks, nada disso é necessário.
Crie um webhook
curl -X POST "https://app.argorant.com/api/v1/webhooks" \
-H "Authorization: Bearer $ARGORANT_API_KEY" -H "Idempotency-Key: hook-crm-1" \
-H "Content-Type: application/json" \
-d '{"url":"https://hooks.yourcompany.example/argorant","events":["reply.positive","email.bounced","export.ready"]}'O endereço precisa ser um endereço público https://. A resposta traz o secret de assinatura. Ele aparece só uma vez, então guarde-o agora. Cada conta pode ter até 10 webhooks ativados e 50 no total. Adicionar um endereço que você já tem altera esse webhook (os novos eventos, ativado) e responde 200 com existing: true e sem novo secret.
Criar um webhook exige o plano Pro ou superior, o seu ou o de um workspace do qual você é membro da equipe; caso contrário, você recebe 402 plan_required. Cada pessoa tem o próprio limite. Um evento desconhecido responde 400 invalid_webhook_events, e um 11º webhook ativado ou um 51º no total responde 400 webhook_limit_reached.
| Chamada | O que faz |
|---|---|
GET /api/v1/webhooks | Seus webhooks e todos os eventos que você pode escolher |
PATCH /api/v1/webhooks/{id} | Altera a URL ou os eventos, ou desativa o webhook com "active": false |
DELETE /api/v1/webhooks/{id} | Remove o webhook |
POST /api/v1/webhooks/{id}/test | Envia uma chamada de teste assinada com o data de exemplo de um evento e "test": true |
GET /api/v1/webhooks/{id}/deliveries | Chamadas recentes com o resultado e a próxima tentativa |
O que o seu servidor recebe
POST /hooks/argorant
Content-Type: application/json
User-Agent: Argorant-Webhooks/1.0
X-Argorant-Event: reply.positive
X-Argorant-Delivery: 8842
X-Argorant-Signature: sha256=5d41402abc4b2a76b9719d911017c592...
{"event": "reply.positive", "delivery_id": "8842", "created_at": "2026-11-07T09:15:03+00:00",
"data": {"classification": "positive", "lead_email": "maya.chen@linfieldsystems.example", "campaign_id": "7f3a2c1e-9b4d-4e8a-a1c2-5d6e7f8a9b0c", "subject": "Re: Quick question, Maya", "snippet": "Happy to talk. Does Thursday 10:00 work?", "reply_id": "c4e1a9b2-6d3f-4a7e-9b1c-2f8d0e5a7c63", "lead_id": "0c9d8e7f-6a5b-4c3d-8e2f-1a0b9c8d7e6f", "received_at": "2026-11-07T09:14:01.482113+00:00"}}Toda chamada tem as mesmas quatro chaves: event, delivery_id (um número enviado como texto, igual a X-Argorant-Delivery), created_at e data. Responda com qualquer status 2xx em poucos segundos. Faça o trabalho demorado depois de responder. Redirecionamentos não são seguidos, então use o endereço final.
Exemplos de payload
Um body completo por evento, do jeito que o seu servidor o recebe. export.ready e list.ready também trazem status_api_path (e download_api_path nas exportações), caminhos antigos mantidos para integrações existentes; eles foram omitidos abaixo. Use status_url e download_url.
reply.received
{"event": "reply.received", "delivery_id": "8841", "created_at": "2026-11-07T09:14:03+00:00",
"data": {"classification": null, "lead_email": "maya.chen@linfieldsystems.example", "campaign_id": "7f3a2c1e-9b4d-4e8a-a1c2-5d6e7f8a9b0c", "subject": "Re: Quick question, Maya", "snippet": "Happy to talk. Does Thursday 10:00 work?", "reply_id": "c4e1a9b2-6d3f-4a7e-9b1c-2f8d0e5a7c63", "lead_id": "0c9d8e7f-6a5b-4c3d-8e2f-1a0b9c8d7e6f", "received_at": "2026-11-07T09:14:01.482113+00:00"}}reply.positive
{"event": "reply.positive", "delivery_id": "8842", "created_at": "2026-11-07T09:15:03+00:00",
"data": {"classification": "positive", "lead_email": "maya.chen@linfieldsystems.example", "campaign_id": "7f3a2c1e-9b4d-4e8a-a1c2-5d6e7f8a9b0c", "subject": "Re: Quick question, Maya", "snippet": "Happy to talk. Does Thursday 10:00 work?", "reply_id": "c4e1a9b2-6d3f-4a7e-9b1c-2f8d0e5a7c63", "lead_id": "0c9d8e7f-6a5b-4c3d-8e2f-1a0b9c8d7e6f", "received_at": "2026-11-07T09:14:01.482113+00:00"}}email.bounced
{"event": "email.bounced", "delivery_id": "8843", "created_at": "2026-11-07T09:16:03+00:00",
"data": {"lead_email": "maya.chen@linfieldsystems.example", "campaign_id": "7f3a2c1e-9b4d-4e8a-a1c2-5d6e7f8a9b0c", "subject": "Quick question, Maya"}}email.unsubscribed
{"event": "email.unsubscribed", "delivery_id": "8844", "created_at": "2026-11-07T09:17:03+00:00",
"data": {"classification": "unsubscribe", "lead_email": "maya.chen@linfieldsystems.example", "campaign_id": "7f3a2c1e-9b4d-4e8a-a1c2-5d6e7f8a9b0c", "subject": "", "snippet": "", "source": "unsubscribe_link"}}campaign.paused
{"event": "campaign.paused", "delivery_id": "8845", "created_at": "2026-11-07T09:18:03+00:00",
"data": {"campaign_id": "7f3a2c1e-9b4d-4e8a-a1c2-5d6e7f8a9b0c", "campaign_name": "Q4 CFO outreach", "reason": "campaign_email_allowance", "message": "Monthly email limit reached. All 300,000 campaign emails for this month are used. Sending resumes on December 1, 2026, or right after an upgrade.", "campaign_emails": {"tier": "pro", "allowance": 300000, "used": 300000, "remaining": 0, "period": "month", "resets_on": "2026-12-01", "reason": "allowance_used", "trial_ends_at": null, "trial_days_left": null}}}campaign.resumed
{"event": "campaign.resumed", "delivery_id": "8846", "created_at": "2026-11-07T09:19:03+00:00",
"data": {"campaign_id": "7f3a2c1e-9b4d-4e8a-a1c2-5d6e7f8a9b0c", "campaign_name": "Q4 CFO outreach", "reason": "campaign_email_allowance", "message": "Sending resumed.", "campaign_emails": {"tier": "pro", "allowance": 300000, "used": 0, "remaining": 300000, "period": "month", "resets_on": "2027-01-01", "reason": "", "trial_ends_at": null, "trial_days_left": null}}}export.ready
{"event": "export.ready", "delivery_id": "8847", "created_at": "2026-11-07T09:20:03+00:00",
"data": {"job_id": 84213, "status": "done", "total_rows": 500, "verified_rows": 463, "status_url": "/api/v1/exports/84213", "download_url": "/api/v1/exports/84213/download"}}list.ready
{"event": "list.ready", "delivery_id": "8848", "created_at": "2026-11-07T09:21:03+00:00",
"data": {"list_id": "312", "list_name": "DACH CFOs", "job_id": 5120, "status": "done", "total_items": 1188, "note": "1,240 matched: 1,188 added, 52 already in the list.", "status_url": "/api/v1/lists/312"}}verification.completed
{"event": "verification.completed", "delivery_id": "8849", "created_at": "2026-11-07T09:22:03+00:00",
"data": {"email": "maya.chen@linfieldsystems.example", "status": "valid", "deliverable": true, "is_role_based": false, "is_free": false, "is_disposable": false}}segment.new_matches
{"event": "segment.new_matches", "delivery_id": "8850", "created_at": "2026-11-07T09:23:03+00:00",
"data": {"list_id": "312", "list_name": "DACH CFOs", "previous_total": 1188, "current_total": 1214, "new_matches": 26}}lead.created
{"event": "lead.created", "delivery_id": "8851", "created_at": "2026-11-07T09:24:03+00:00",
"data": {"campaign_id": "7f3a2c1e-9b4d-4e8a-a1c2-5d6e7f8a9b0c", "campaign_name": "Q4 CFO outreach", "count": 2, "leads": [{"lead_id": "0c9d8e7f-6a5b-4c3d-8e2f-1a0b9c8d7e6f", "email": "maya.chen@linfieldsystems.example", "first_name": "Maya", "last_name": "Chen", "company": "Linfield Systems", "title": "CFO", "status": "pending", "custom_fields": {"tags": ["q4"]}, "added_at": "2026-11-07T08:02:11.204519+00:00"}, {"lead_id": "5e2a7c91-3b4d-4f6e-8a1c-9d0b2e4f6a83", "email": "alex.rivera@linfieldsystems.example", "first_name": "Alex", "last_name": "Rivera", "company": "Linfield Systems", "title": "Head of Finance", "status": "pending", "custom_fields": {"tags": ["q4"]}, "added_at": "2026-11-07T08:02:11.204519+00:00"}]}}campaign.status_changed
{"event": "campaign.status_changed", "delivery_id": "8852", "created_at": "2026-11-07T09:25:03+00:00",
"data": {"campaign_id": "7f3a2c1e-9b4d-4e8a-a1c2-5d6e7f8a9b0c", "campaign_name": "Q4 CFO outreach", "from": "draft", "to": "active", "changed_at": "2026-11-07T08:05:37.918204+00:00"}}email.sent
{"event": "email.sent", "delivery_id": "8853", "created_at": "2026-11-07T09:26:03+00:00",
"data": {"campaign_id": "7f3a2c1e-9b4d-4e8a-a1c2-5d6e7f8a9b0c", "campaign_name": "Q4 CFO outreach", "count": 1, "emails": [{"email_id": "9a7b5c3d-1e2f-4a6b-8c0d-2e4f6a8b0c1d", "lead_id": "0c9d8e7f-6a5b-4c3d-8e2f-1a0b9c8d7e6f", "lead_email": "maya.chen@linfieldsystems.example", "subject": "Quick question, Maya", "step": 1, "mailbox": "outreach@yourcompany-mail.example", "sent_at": "2026-11-07T08:31:12.550731+00:00"}]}}reply.label_changed
{"event": "reply.label_changed", "delivery_id": "8854", "created_at": "2026-11-07T09:27:03+00:00",
"data": {"reply_id": "c4e1a9b2-6d3f-4a7e-9b1c-2f8d0e5a7c63", "lead_id": "0c9d8e7f-6a5b-4c3d-8e2f-1a0b9c8d7e6f", "lead_email": "maya.chen@linfieldsystems.example", "campaign_id": "7f3a2c1e-9b4d-4e8a-a1c2-5d6e7f8a9b0c", "subject": "Re: Quick question, Maya", "from": null, "to": "meeting_request", "changed_at": "2026-11-07T09:20:41Z"}}Chamadas de teste
POST /api/v1/webhooks/{id}/test envia uma chamada assinada com o data de exemplo de um dos eventos do webhook, igual aos de cima, mais "test": true, para que o seu código saiba diferenciar um teste de um evento real. Envie {"event": "lead.created"} para escolher o evento; sem isso, é usado o primeiro evento do webhook. Um evento que o webhook não recebe responde 400 event_not_subscribed.
{"event": "reply.positive", "delivery_id": "9012", "created_at": "2026-11-07T09:30:03+00:00",
"data": {"classification": "positive", "lead_email": "maya.chen@linfieldsystems.example", "campaign_id": "7f3a2c1e-9b4d-4e8a-a1c2-5d6e7f8a9b0c", "subject": "Re: Quick question, Maya", "snippet": "Happy to talk. Does Thursday 10:00 work?", "reply_id": "c4e1a9b2-6d3f-4a7e-9b1c-2f8d0e5a7c63", "lead_id": "0c9d8e7f-6a5b-4c3d-8e2f-1a0b9c8d7e6f", "received_at": "2026-11-07T09:14:01.482113+00:00", "test": true}}Verifique a assinatura
A assinatura é o HMAC-SHA256 do body bruto com o seu secret. Compare-a antes de confiar na chamada. Use os bytes do body exatamente como chegaram, antes de qualquer parsing de JSON.
import hmac, hashlib
def is_from_argorant(secret: str, raw_body: bytes, signature_header: str) -> bool:
expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, signature_header)const crypto = require("crypto");
function isFromArgorant(secret, rawBody, signatureHeader) {
const expected = Buffer.from("sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex"));
const given = Buffer.from(signatureHeader || "");
return given.length === expected.length && crypto.timingSafeEqual(expected, given);
}O body assinado contém delivery_id e created_at, então nenhum dos dois pode ser alterado sem quebrar a assinatura. Guarde os ids de entrega que você já processou e pule um que você já viu. Assim, uma chamada repetida não causa nenhum dano.
Quando o seu servidor está fora do ar
Uma chamada que falha é tentada de novo depois de 1 minuto, 5 minutos, 30 minutos, 2 horas e 6 horas, ou seja, até 6 vezes. X-Argorant-Delivery continua o mesmo em todas as tentativas de um evento, então use-o para pular eventos que você já processou. Depois de 50 chamadas com falha seguidas, o webhook é desativado; ative-o de novo com PATCH e "active": true. Um 404 não conta: a chamada é tentada de novo como acima, e o webhook só é desativado quando o seu endereço responde 404 por 7 dias sem que nenhuma chamada chegue. Um 410 Gone significa que o endereço deixou de existir de vez, então o webhook é excluído na hora; adicione-o de novo quando quiser voltar a receber as chamadas.
Tags de caixas de e-mail
Coloque tags em novas caixas de e-mail já no pedido, e coloque tags ou assinaturas em centenas de caixas existentes em uma etapa, por exemplo em todas as caixas de um pedido.
Envie pessoas para as suas outras ferramentas
Envie uma exportação para a ferramenta de envio que você já usa, na sua própria conta dela. Uma lista vai como a exportação dela. Incluído a partir do plano Pro.