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
| Evento | Quando arriva | Cosa contiene data |
|---|---|---|
reply.received | Una 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 etichetta | classification, lead_email, campaign_id, subject, snippet, reply_id, lead_id, received_at |
reply.positive | Hai 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'etichetta | classification, lead_email, campaign_id, subject, snippet, reply_id, lead_id, received_at |
email.bounced | Un'email di campagna è rimbalzata. Non viene inviato se quella persona aveva già risposto | lead_email, campaign_id, subject |
email.unsubscribed | Qualcuno ha usato il link di disiscrizione, oppure hai dato alla sua risposta l'etichetta Disiscrizione | classification, 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.paused | Argorant 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 nulla | campaign_id, campaign_name, reason, message, e campaign_emails (piano) oppure metrics e url (pausa automatica) |
campaign.resumed | Le 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 nulla | campaign_id, campaign_name, reason, message, campaign_emails |
export.ready | Un'esportazione è terminata. Non viene inviato se non è riuscita | job_id, status, total_rows, verified_rows, status_url, download_url, status_api_path, download_api_path |
list.ready | Una lista ha finito di riempirsi, anche dopo che hai aggiunto altre persone. Non viene inviato se il riempimento non è riuscito | list_id, list_name, job_id, status, total_items, note, status_url, status_api_path |
verification.completed | Una singola verifica email con una chiave API è terminata | email, status, deliverable, is_role_based, is_free, is_disposable |
segment.new_matches | Una lista di ricerca salvata ha più persone corrispondenti rispetto all'ultimo conteggio. Le liste vengono controllate circa ogni 30 minuti | list_id, list_name, previous_total, current_total, new_matches |
lead.created | Sono 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 escluse | campaign_id, campaign_name, count, leads, ognuno con lead_id, email, first_name, last_name, company, title, status, custom_fields, added_at |
campaign.status_changed | Lo 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.resumed | campaign_id, campaign_name, from, to, changed_at |
email.sent | Sono partite email di campagna. Arriva entro circa un minuto dall'invio, una consegna per campagna con al massimo 100 email | campaign_id, campaign_name, count, emails, ognuna con email_id, lead_id, lead_email, subject, step, mailbox, sent_at |
reply.label_changed | Qualcuno 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 nulla | reply_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
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.
| Chiamata | Cosa fa |
|---|---|
GET /api/v1/webhooks | I 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}/test | Invia una chiamata di test firmata con i data di esempio di un evento e "test": true |
GET /api/v1/webhooks/{id}/deliveries | Le chiamate recenti con il loro esito e il prossimo tentativo |
Cosa riceve il tuo server
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
{"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"}}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.
{"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.
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);
}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.
Tag delle caselle
Assegna i tag alle nuove caselle quando le ordini, e assegna tag o firme a centinaia di caselle esistenti in un solo passaggio, per esempio a tutte le caselle di un ordine.
Invia le persone ai tuoi altri strumenti
Invia un'esportazione allo strumento di invio che usi già, nel tuo account lì. Una lista viene inviata come sua esportazione. Incluso dal piano Pro.