ArgorantDocs

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énementQuand il se déclencheContenu de data
reply.receivedUne 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.positiveVous 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.bouncedUn e-mail de campagne a rebondi. Non envoyé si cette personne avait déjà répondulead_email, campaign_id, subject
email.unsubscribedQuelqu'un a utilisé le lien de désinscription, ou vous avez donné à sa réponse le libellé Se désinscrireclassification, 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.pausedArgorant 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 riencampaign_id, campaign_name, reason, message, et campaign_emails (forfait) ou metrics et url (pause automatique)
campaign.resumedDes 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 riencampaign_id, campaign_name, reason, message, campaign_emails
export.readyUn export est terminé. Non envoyé en cas d'échecjob_id, status, total_rows, verified_rows, status_url, download_url, status_api_path, download_api_path
list.readyUne 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.completedUne vérification d'un seul e-mail avec une clé API est terminéeemail, status, deliverable, is_role_based, is_free, is_disposable
segment.new_matchesUne 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 minuteslist_id, list_name, previous_total, current_total, new_matches
lead.createdDes 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 excluescampaign_id, campaign_name, count, leads, chacun avec lead_id, email, first_name, last_name, company, title, status, custom_fields, added_at
campaign.status_changedLe 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.resumedcampaign_id, campaign_name, from, to, changed_at
email.sentDes e-mails de campagne sont partis. Arrive environ une minute après l'envoi, une livraison par campagne avec jusqu'à 100 e-mailscampaign_id, campaign_name, count, emails, chacun avec email_id, lead_id, lead_email, subject, step, mailbox, sent_at
reply.label_changedQuelqu'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 rienreply_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

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

AppelCe qu'il fait
GET /api/v1/webhooksVos 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}/testEnvoie un appel de test signé avec les data d'exemple d'un événement et "test": true
GET /api/v1/webhooks/{id}/deliveriesLes appels récents avec leur résultat et la prochaine tentative

Ce que reçoit votre serveur

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

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

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

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.

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

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.

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);
}

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.

Sur cette page