ArgorantDocs

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

EventoQuando é disparadoO que data contém
reply.receivedUma 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ótuloclassification, lead_email, campaign_id, subject, snippet, reply_id, lead_id, received_at
reply.positiveVocê 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 rotulaclassification, lead_email, campaign_id, subject, snippet, reply_id, lead_id, received_at
email.bouncedUm e-mail de campanha deu bounce. Não é enviado quando essa pessoa já tinha respondido anteslead_email, campaign_id, subject
email.unsubscribedAlguém usou o link de descadastro, ou você deu à resposta dessa pessoa o rótulo Descadastrarclassification, 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.pausedO 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 nadacampaign_id, campaign_name, reason, message, e campaign_emails (plano) ou metrics e url (pausa automática)
campaign.resumedHá 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 nadacampaign_id, campaign_name, reason, message, campaign_emails
export.readyUma exportação terminou. Não é enviado quando ela falhoujob_id, status, total_rows, verified_rows, status_url, download_url, status_api_path, download_api_path
list.readyUma lista terminou de ser preenchida, também depois que você adicionou mais pessoas. Não é enviado quando o preenchimento falhoulist_id, list_name, job_id, status, total_items, note, status_url, status_api_path
verification.completedUma verificação de um único e-mail com uma chave de API terminouemail, status, deliverable, is_role_based, is_free, is_disposable
segment.new_matchesUma lista de busca salva tem mais pessoas correspondentes do que na última contagem. As listas são verificadas a cada 30 minutos, mais ou menoslist_id, list_name, previous_total, current_total, new_matches
lead.createdPessoas 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 foracampaign_id, campaign_name, count, leads, cada um com lead_id, email, first_name, last_name, company, title, status, custom_fields, added_at
campaign.status_changedO 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.resumedcampaign_id, campaign_name, from, to, changed_at
email.sentE-mails de campanha saíram. Chega em cerca de um minuto após o envio, uma entrega por campanha com até 100 e-mailscampaign_id, campaign_name, count, emails, cada um com email_id, lead_id, lead_email, subject, step, mailbox, sent_at
reply.label_changedAlgué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 nadareply_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

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

ChamadaO que faz
GET /api/v1/webhooksSeus 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}/testEnvia uma chamada de teste assinada com o data de exemplo de um evento e "test": true
GET /api/v1/webhooks/{id}/deliveriesChamadas recentes com o resultado e a próxima tentativa

O que o seu servidor recebe

HTTP
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

JSON
{"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

JSON
{"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

JSON
{"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

JSON
{"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

JSON
{"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

JSON
{"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

JSON
{"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

JSON
{"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

JSON
{"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

JSON
{"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

JSON
{"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

JSON
{"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

JSON
{"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

JSON
{"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.

JSON
{"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.

Python
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)
Node
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.

Nesta página