Webhooks
Recevez un appel signé sur votre serveur quand une réponse arrive, qu'une personne est intéressée, qu'un e-mail rebondit, qu'une liste ou un export est prêt. Inclus à partir du forfait Pro.
Événements
| Événement | Quand il se déclenche | Contenu de data |
|---|---|---|
reply.received | Une personne a répondu à l'une de vos campagnes. Les réponses automatiques d'absence sont exclues, sauf si votre espace de travail a masqué son libellé Absent. Il se déclenche aussi quand vous faites passer une réponse du libellé Absent à un autre libellé | classification, lead_email, campaign_id, subject, snippet, reply_id, lead_id, received_at |
reply.positive | Vous avez donné à une réponse le libellé Intéressé ou Demande de rendez-vous, dans l'app ou avec POST /api/v1/inbox/{id}/classify. Il ne se déclenche que lorsque le libellé change : une même réponse envoie donc reply.received à son arrivée et reply.positive quand vous lui donnez ce libellé | classification, lead_email, campaign_id, subject, snippet, reply_id, lead_id, received_at |
email.bounced | Un e-mail de campagne a rebondi. Non envoyé si cette personne avait déjà répondu | lead_email, campaign_id, subject |
email.unsubscribed | Quelqu'un a utilisé le lien de désinscription, ou vous avez donné à sa réponse le libellé Se désinscrire | classification, lead_email, campaign_id, subject, snippet, et source pour le lien de désinscription, ou reply_id, lead_id et received_at quand l'événement vient d'un libellé |
campaign.paused | Argorant a mis en pause une campagne en cours : les e-mails de campagne de votre forfait sont épuisés (ou l'essai ou le forfait a pris fin), ou la campagne s'est mise en pause d'elle-même à cause de rebonds ou de boîtes mail hors ligne. Votre propre mise en pause n'envoie rien | campaign_id, campaign_name, reason, message, et campaign_emails (forfait) ou metrics et url (pause automatique) |
campaign.resumed | Des e-mails de campagne sont de nouveau disponibles (un nouveau mois ou un forfait supérieur) : une campagne mise en pause par le forfait envoie donc de nouveau. Votre propre lancement n'envoie rien | campaign_id, campaign_name, reason, message, campaign_emails |
export.ready | Un export est terminé. Non envoyé en cas d'échec | job_id, status, total_rows, verified_rows, status_url, download_url, status_api_path, download_api_path |
list.ready | Une liste a fini de se remplir, y compris après l'ajout de nouvelles personnes. Non envoyé si le remplissage a échoué | list_id, list_name, job_id, status, total_items, note, status_url, status_api_path |
verification.completed | Une vérification d'un seul e-mail avec une clé API est terminée | email, status, deliverable, is_role_based, is_free, is_disposable |
segment.new_matches | Une liste de recherche enregistrée compte plus de personnes correspondantes que lors du dernier comptage. Les listes sont vérifiées environ toutes les 30 minutes | list_id, list_name, previous_total, current_total, new_matches |
lead.created | Des personnes ont été ajoutées à une campagne, dans l'app, via l'API, depuis un fichier, depuis une liste ou par un déplacement. Une livraison par lot reçu par la campagne : un import important arrive donc en plusieurs livraisons. Les personnes retirées avant l'envoi de la livraison sont exclues | campaign_id, campaign_name, count, leads, chacun avec lead_id, email, first_name, last_name, company, title, status, custom_fields, added_at |
campaign.status_changed | Le statut d'une campagne a changé, de votre fait ou de celui d'Argorant : un lancement, une pause, un arrêt ou un archivage, ou une pause pour cause d'e-mails de campagne épuisés, de rebonds ou de boîtes mail hors ligne. Il se déclenche aussi en même temps que campaign.paused et campaign.resumed | campaign_id, campaign_name, from, to, changed_at |
email.sent | Des e-mails de campagne sont partis. Arrive environ une minute après l'envoi, une livraison par campagne avec jusqu'à 100 e-mails | campaign_id, campaign_name, count, emails, chacun avec email_id, lead_id, lead_email, subject, step, mailbox, sent_at |
reply.label_changed | Quelqu'un a défini ou modifié le libellé d'une réponse, dans la boîte de réception de l'app ou avec POST /api/v1/inbox/{id}/classify. Redonner le même libellé n'envoie rien | reply_id, lead_id, lead_email, campaign_id, subject, from, to, changed_at |
Les événements de campagne vont aux webhooks du propriétaire de l'espace de travail et de chaque membre actif de l'équipe, pour que chacun puisse les diriger vers ses propres outils. Les exports, les listes et les vérifications vont aux webhooks de la personne qui les a lancés. Les nouvelles correspondances vont aux webhooks du propriétaire de la liste.
Dans les événements de réponse, classification vaut null pour une réponse qui vient d'arriver, puis la clé du libellé une fois qu'il a été défini, par exemple positive ou meeting_request. subject contient jusqu'à 300 caractères et snippet jusqu'à 500 caractères de texte brut. reply_id désigne la réponse, lead_id la personne dans la campagne et received_at le moment où la réponse est arrivée. Le reason de campaign.paused vaut campaign_email_allowance quand le forfait a mis la campagne en pause, et auto_pause_bounce_rate, auto_pause_inboxes_offline ou auto_pause quand elle s'est mise en pause d'elle-même. campaign_emails.reason indique pourquoi les e-mails sont épuisés (allowance_used, trial_ended, plan_ended ou confirm_email) et reste vide dans campaign.resumed.
Les valeurs from et to de campaign.status_changed sont draft, active, paused, completed ou archived. Dans reply.label_changed, ce sont des clés de libellé, et from vaut null quand la réponse n'avait pas de libellé. lead.created, campaign.status_changed et email.sent démarrent environ une minute après la création du premier webhook qui les demande ; rien d'antérieur n'est envoyé. Quand votre serveur prend beaucoup de retard, les nouveaux appels email.sent attendent qu'il ait rattrapé son retard ; aucun n'est perdu.
Si vous interrogez plutôt l'API à intervalles réguliers, commencez chaque lecture quelques minutes avant la fin de la précédente et ignorez les identifiants que vous avez déjà. Une ligne peut être enregistrée un instant après l'heure qu'elle porte : une fenêtre qui commence exactement là où la précédente s'est arrêtée peut donc la manquer. Avec les webhooks, rien de tout cela n'est nécessaire.
Créer 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'adresse doit être une adresse https:// publique. La réponse contient le secret de signature. Il n'est affiché qu'une fois : conservez-le tout de suite. Chaque compte peut avoir jusqu'à 10 webhooks activés et 50 au total. Si vous ajoutez une adresse que vous avez déjà, ce webhook est mis à jour (nouveaux événements, activé) et la réponse est 200 avec existing: true, sans nouveau secret.
Créer un webhook nécessite le forfait Pro ou supérieur, le vôtre ou celui d'un espace de travail dont vous êtes membre de l'équipe, sinon vous obtenez 402 plan_required. Chaque personne a sa propre limite. Un événement inconnu renvoie 400 invalid_webhook_events, et un 11e webhook activé ou un 51e au total 400 webhook_limit_reached.
| Appel | Ce qu'il fait |
|---|---|
GET /api/v1/webhooks | Vos webhooks et tous les événements que vous pouvez choisir |
PATCH /api/v1/webhooks/{id} | Modifie l'URL ou les événements, ou le désactive avec "active": false |
DELETE /api/v1/webhooks/{id} | Le supprime |
POST /api/v1/webhooks/{id}/test | Envoie un appel de test signé avec les data d'exemple d'un événement et "test": true |
GET /api/v1/webhooks/{id}/deliveries | Les appels récents avec leur résultat et la prochaine tentative |
Ce que reçoit votre serveur
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"}}Chaque appel a les mêmes quatre clés : event, delivery_id (un nombre envoyé sous forme de texte, identique à X-Argorant-Delivery), created_at et data. Répondez avec n'importe quel statut 2xx en quelques secondes. Faites le travail lent après avoir répondu. Les redirections ne sont pas suivies : utilisez l'adresse finale.
Exemples de contenu
Un corps complet par événement, tel que votre serveur le reçoit. export.ready et list.ready contiennent aussi status_api_path (et download_api_path pour les exports), d'anciens chemins conservés pour les intégrations existantes ; ils sont omis ci-dessous. Utilisez status_url et 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"}}Appels de test
POST /api/v1/webhooks/{id}/test envoie un appel signé avec les data d'exemple de l'un des événements du webhook, les mêmes que ci-dessus, plus "test": true, pour que votre code puisse distinguer un test d'un vrai événement. Envoyez {"event": "lead.created"} pour choisir l'événement ; sans cela, le premier événement du webhook est utilisé. Un événement que le webhook ne reçoit pas renvoie 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}}Vérifier la signature
La signature est le HMAC-SHA256 du corps brut avec votre secret. Comparez-la avant de faire confiance à l'appel. Utilisez les octets du corps exactement tels qu'ils sont arrivés, avant tout 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);
}Le corps signé contient delivery_id et created_at : ni l'un ni l'autre ne peut être modifié sans casser la signature. Gardez les identifiants de livraison déjà traités et ignorez ceux que vous avez déjà vus. Un appel rejoué devient ainsi inoffensif.
Quand votre serveur est indisponible
Un appel qui échoue est retenté après 1 minute, 5 minutes, 30 minutes, 2 heures et 6 heures, donc jusqu'à 6 fois. X-Argorant-Delivery reste identique pour toutes les tentatives d'un même événement : servez-vous-en pour ignorer les événements déjà traités. Après 50 appels en échec d'affilée, le webhook est désactivé ; réactivez-le avec PATCH et "active": true. Un 404 n'est pas compté : l'appel est retenté comme ci-dessus, et le webhook n'est désactivé que si votre adresse a répondu 404 pendant 7 jours sans qu'aucun appel ne passe. Un 410 Gone signifie que l'adresse a disparu pour de bon : le webhook est alors supprimé aussitôt ; ajoutez-le de nouveau si vous voulez recevoir les appels.
Tags des boîtes mail
Taguez les nouvelles boîtes mail dès la commande, et taguez ou signez des centaines de boîtes mail existantes en une étape, par exemple toutes celles d'une commande.
Envoyer des personnes vers vos autres outils
Envoyez un export dans l'outil d'envoi que vous utilisez déjà, dans votre propre compte. Une liste part sous forme d'export. Inclus à partir du forfait Pro.