ArgorantDocs

Webhook

Ricevi una chiamata firmata sul tuo server quando arriva una risposta, qualcuno è interessato, un'email rimbalza, una lista o un'esportazione è pronta. Incluso dal piano Pro.

Eventi

EventoQuando arrivaCosa contiene data
reply.receivedUna persona ha risposto a una delle tue campagne. Le risposte automatiche di assenza sono escluse, a meno che il tuo workspace non abbia nascosto l'etichetta Fuori ufficio. Arriva anche quando sposti una risposta da Fuori ufficio a un'altra etichettaclassification, lead_email, campaign_id, subject, snippet, reply_id, lead_id, received_at
reply.positiveHai dato a una risposta l'etichetta Interessato o Richiesta di appuntamento, nell'app o con POST /api/v1/inbox/{id}/classify. Arriva solo quando l'etichetta cambia, quindi una risposta invia reply.received quando arriva e reply.positive quando le dai l'etichettaclassification, lead_email, campaign_id, subject, snippet, reply_id, lead_id, received_at
email.bouncedUn'email di campagna è rimbalzata. Non viene inviato se quella persona aveva già rispostolead_email, campaign_id, subject
email.unsubscribedQualcuno ha usato il link di disiscrizione, oppure hai dato alla sua risposta l'etichetta Disiscrizioneclassification, lead_email, campaign_id, subject, snippet, più source per il link di disiscrizione, oppure reply_id, lead_id e received_at quando viene da un'etichetta
campaign.pausedArgorant ha messo in pausa una campagna attiva: le email di campagna del tuo piano sono finite (o la prova o il piano sono terminati), oppure la campagna si è messa in pausa da sola per rimbalzi o caselle offline. Una pausa fatta da te non invia nullacampaign_id, campaign_name, reason, message, e campaign_emails (piano) oppure metrics e url (pausa automatica)
campaign.resumedLe email di campagna sono di nuovo disponibili (un nuovo mese o un piano più grande), quindi una campagna messa in pausa dal piano riprende a inviare. Un avvio fatto da te non invia nullacampaign_id, campaign_name, reason, message, campaign_emails
export.readyUn'esportazione è terminata. Non viene inviato se non è riuscitajob_id, status, total_rows, verified_rows, status_url, download_url, status_api_path, download_api_path
list.readyUna lista ha finito di riempirsi, anche dopo che hai aggiunto altre persone. Non viene inviato se il riempimento non è riuscitolist_id, list_name, job_id, status, total_items, note, status_url, status_api_path
verification.completedUna singola verifica email con una chiave API è terminataemail, status, deliverable, is_role_based, is_free, is_disposable
segment.new_matchesUna lista di ricerca salvata ha più persone corrispondenti rispetto all'ultimo conteggio. Le liste vengono controllate circa ogni 30 minutilist_id, list_name, previous_total, current_total, new_matches
lead.createdSono state aggiunte persone a una campagna, nell'app, tramite l'API, da un file, da una lista o con uno spostamento. Una consegna per ogni gruppo di persone che la campagna ha preso in carico, quindi un'importazione grande arriva in più consegne. Le persone rimosse di nuovo prima dell'invio della consegna sono esclusecampaign_id, campaign_name, count, leads, ognuno con lead_id, email, first_name, last_name, company, title, status, custom_fields, added_at
campaign.status_changedLo stato di una campagna è cambiato, per mano tua o di Argorant: un avvio, una pausa, uno stop o un'archiviazione, oppure una pausa per email di campagna, rimbalzi o caselle offline. Arriva anche insieme a campaign.paused e campaign.resumedcampaign_id, campaign_name, from, to, changed_at
email.sentSono partite email di campagna. Arriva entro circa un minuto dall'invio, una consegna per campagna con al massimo 100 emailcampaign_id, campaign_name, count, emails, ognuna con email_id, lead_id, lead_email, subject, step, mailbox, sent_at
reply.label_changedQualcuno ha impostato o cambiato l'etichetta di una risposta, nella posta in arrivo dell'app o con POST /api/v1/inbox/{id}/classify. Impostare di nuovo la stessa etichetta non invia nullareply_id, lead_id, lead_email, campaign_id, subject, from, to, changed_at

Gli eventi delle campagne vanno ai webhook del proprietario del workspace e di ogni membro attivo del team, così ognuno può inviarli ai propri strumenti. Esportazioni, liste e verifiche vanno ai webhook della persona che le ha avviate. Le nuove corrispondenze vanno ai webhook del proprietario della lista.

Negli eventi delle risposte classification è null per una risposta appena arrivata, e diventa la chiave dell'etichetta quando qualcuno ne ha impostata una, per esempio positive o meeting_request. subject contiene fino a 300 caratteri e snippet fino a 500 caratteri di testo semplice. reply_id è la risposta, lead_id la persona nella campagna e received_at il momento in cui è arrivata la risposta. reason di campaign.paused è campaign_email_allowance quando è stato il piano a mettere in pausa la campagna, e auto_pause_bounce_rate, auto_pause_inboxes_offline o auto_pause quando si è messa in pausa da sola. campaign_emails.reason indica perché le email sono finite (allowance_used, trial_ended, plan_ended o confirm_email) ed è vuoto in campaign.resumed.

from e to di campaign.status_changed sono draft, active, paused, completed o archived. In reply.label_changed sono chiavi di etichetta, e from è null quando la risposta non aveva un'etichetta. lead.created, campaign.status_changed e email.sent partono circa un minuto dopo la creazione del primo webhook che li richiede; nulla di precedente viene inviato. Quando il tuo server resta molto indietro, le nuove chiamate email.sent aspettano che recuperi; nessuna va persa.

Se invece leggi l'API a intervalli regolari, fai partire ogni lettura qualche minuto prima della fine di quella precedente e salta gli id che hai già. Una riga può essere salvata un attimo dopo l'orario che riporta, quindi una finestra che parte esattamente dove è finita l'ultima può perderla. Con i webhook non serve nulla di tutto questo.

Crea un 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"]}'

L'indirizzo deve essere un indirizzo pubblico https://. La risposta contiene il secret di firma. Viene mostrato una sola volta, quindi salvalo subito. Ogni account può avere fino a 10 webhook attivi e 50 in tutto. Se aggiungi un indirizzo che hai già, modifichi quel webhook (i nuovi eventi, attivato) e la risposta è 200 con existing: true e nessun nuovo secret.

Per creare un webhook serve il piano Pro o superiore, il tuo o quello di un workspace di cui sei membro del team, altrimenti ricevi 402 plan_required. Ogni persona ha il proprio limite. Un evento sconosciuto risponde 400 invalid_webhook_events, e un 11° webhook attivo o un 51° in tutto 400 webhook_limit_reached.

ChiamataCosa fa
GET /api/v1/webhooksI tuoi webhook e tutti gli eventi che puoi scegliere
PATCH /api/v1/webhooks/{id}Cambia l'URL o gli eventi, oppure lo disattiva con "active": false
DELETE /api/v1/webhooks/{id}Lo rimuove
POST /api/v1/webhooks/{id}/testInvia una chiamata di test firmata con i data di esempio di un evento e "test": true
GET /api/v1/webhooks/{id}/deliveriesLe chiamate recenti con il loro esito e il prossimo tentativo

Cosa riceve il tuo server

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"}}

Ogni chiamata ha le stesse quattro chiavi: event, delivery_id (un numero inviato come testo, uguale a X-Argorant-Delivery), created_at e data. Rispondi con un qualsiasi stato 2xx entro pochi secondi. Fai il lavoro lento dopo aver risposto. I reindirizzamenti non vengono seguiti, quindi usa l'indirizzo finale.

Payload di esempio

Un body completo per ogni evento, così come lo riceve il tuo server. export.ready e list.ready contengono anche status_api_path (e download_api_path per le esportazioni), percorsi più vecchi mantenuti per le integrazioni esistenti; qui sotto sono omessi. Usa 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"}}

Chiamate di test

POST /api/v1/webhooks/{id}/test invia una chiamata firmata con i data di esempio di uno degli eventi del webhook, uguali a quelli sopra, più "test": true, così il tuo codice distingue un test da un evento reale. Invia {"event": "lead.created"} per scegliere l'evento; senza, viene usato il primo evento del webhook. Un evento che il webhook non riceve risponde 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}}

Controlla la firma

La firma è l'HMAC-SHA256 del body grezzo con il tuo secret. Confrontala prima di fidarti della chiamata. Usa i byte del body esattamente come sono arrivati, prima di qualsiasi parsing 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);
}

Il body firmato contiene delivery_id e created_at, quindi nessuno dei due si può modificare senza rompere la firma. Tieni traccia degli id di consegna che hai gestito e salta quelli che hai già visto. Così una chiamata ripetuta non fa danni.

Quando il tuo server non risponde

Una chiamata non riuscita viene ritentata dopo 1 minuto, 5 minuti, 30 minuti, 2 ore e 6 ore, quindi fino a 6 volte. X-Argorant-Delivery resta uguale per ogni tentativo dello stesso evento, quindi usalo per saltare gli eventi che hai già gestito. Dopo 50 chiamate fallite di fila il webhook viene disattivato; riattivalo con PATCH e "active": true. Un 404 non viene contato: la chiamata viene ritentata come sopra, e il webhook viene disattivato solo quando il tuo indirizzo ha risposto 404 per 7 giorni senza che nessuna chiamata andasse a buon fine. Un 410 Gone significa che l'indirizzo non esiste più, quindi il webhook viene eliminato subito; aggiungilo di nuovo quando vuoi tornare a ricevere le chiamate.

In questa pagina