ArgorantDocs

Webhooks

Krijg een ondertekende aanroep naar je server wanneer er een antwoord binnenkomt, iemand geïnteresseerd is, een e-mail bouncet, of een lijst of export klaar is. Inbegrepen vanaf het plan Pro.

Events

EventWanneer het afgaatWat data bevat
reply.receivedIemand heeft geantwoord op een van je campagnes. Automatische afwezigheidsmeldingen vallen weg, tenzij je workspace het label Afwezig heeft verborgen. Het gaat ook af wanneer je een antwoord van Afwezig naar een ander label verplaatstclassification, lead_email, campaign_id, subject, snippet, reply_id, lead_id, received_at
reply.positiveJe hebt een antwoord het label Geïnteresseerd of Afspraakverzoek gegeven, in de app of met POST /api/v1/inbox/{id}/classify. Het gaat alleen af wanneer het label verandert, dus één antwoord stuurt reply.received als het binnenkomt en reply.positive als je het labeltclassification, lead_email, campaign_id, subject, snippet, reply_id, lead_id, received_at
email.bouncedEen campagne-e-mail is gebounced. Niet verstuurd als die persoon eerder heeft geantwoordlead_email, campaign_id, subject
email.unsubscribedIemand heeft de afmeldlink gebruikt, of je hebt diens antwoord het label Afmelden gegevenclassification, lead_email, campaign_id, subject, snippet, en source bij de afmeldlink, of reply_id, lead_id en received_at als het via een label kwam
campaign.pausedArgorant heeft een lopende campagne gepauzeerd: de campagne-e-mails van je plan zijn op (of de proefperiode of het plan is afgelopen), of de campagne heeft zichzelf gepauzeerd door bounces of offline mailboxen. Je eigen pauze stuurt nietscampaign_id, campaign_name, reason, message, en campaign_emails (plan) of metrics en url (zelf gepauzeerd)
campaign.resumedEr zijn weer campagne-e-mails beschikbaar (een nieuwe maand of een groter plan), dus een campagne die door het plan was gepauzeerd, verstuurt weer. Je eigen start stuurt nietscampaign_id, campaign_name, reason, message, campaign_emails
export.readyEen export is klaar. Niet verstuurd als die is misluktjob_id, status, total_rows, verified_rows, status_url, download_url, status_api_path, download_api_path
list.readyEen lijst is klaar met vullen, ook nadat je meer mensen hebt toegevoegd. Niet verstuurd als het vullen is misluktlist_id, list_name, job_id, status, total_items, note, status_url, status_api_path
verification.completedEen losse e-mailcontrole met een API-sleutel is klaaremail, status, deliverable, is_role_based, is_free, is_disposable
segment.new_matchesEen opgeslagen zoeklijst heeft meer passende mensen dan bij de vorige telling. Lijsten worden ongeveer elke 30 minuten gecontroleerdlist_id, list_name, previous_total, current_total, new_matches
lead.createdEr zijn mensen aan een campagne toegevoegd, in de app, via de API, uit een bestand, uit een lijst of door een verplaatsing. Eén levering per batch die de campagne heeft opgenomen, dus een grote import komt binnen als meerdere leveringen. Mensen die weer zijn verwijderd voordat de levering werd verstuurd, vallen wegcampaign_id, campaign_name, count, leads, elk met lead_id, email, first_name, last_name, company, title, status, custom_fields, added_at
campaign.status_changedDe status van een campagne is veranderd, door jou of door Argorant: een start, pauze, stop of archivering, of een pauze vanwege campagne-e-mails, bounces of offline mailboxen. Het gaat ook af naast campaign.paused en campaign.resumedcampaign_id, campaign_name, from, to, changed_at
email.sentEr zijn campagne-e-mails verstuurd. Komt ongeveer een minuut na het versturen binnen, één levering per campagne met maximaal 100 e-mailscampaign_id, campaign_name, count, emails, elk met email_id, lead_id, lead_email, subject, step, mailbox, sent_at
reply.label_changedIemand heeft het label van een antwoord ingesteld of gewijzigd, in de inbox van de app of met POST /api/v1/inbox/{id}/classify. Hetzelfde label opnieuw instellen stuurt nietsreply_id, lead_id, lead_email, campaign_id, subject, from, to, changed_at

Campagne-events gaan naar de webhooks van de eigenaar van de workspace en van elk actief teamlid, zodat ieder ze naar zijn eigen tools kan sturen. Exports, lijsten en controles gaan naar de webhooks van degene die ze heeft gestart. Nieuwe matches gaan naar de webhooks van de eigenaar van de lijst.

In antwoord-events is classification null voor een antwoord dat net is binnengekomen, en de sleutel van het label zodra iemand er een heeft ingesteld, bijvoorbeeld positive of meeting_request. subject bevat tot 300 tekens en snippet tot 500 tekens platte tekst. reply_id is het antwoord, lead_id de persoon in de campagne en received_at het moment waarop het antwoord binnenkwam. reason van campaign.paused is campaign_email_allowance wanneer het plan de campagne heeft gepauzeerd, en auto_pause_bounce_rate, auto_pause_inboxes_offline of auto_pause wanneer ze zichzelf heeft gepauzeerd. campaign_emails.reason zegt waarom de e-mails op waren (allowance_used, trial_ended, plan_ended of confirm_email) en is leeg in campaign.resumed.

from en to van campaign.status_changed zijn draft, active, paused, completed of archived. In reply.label_changed zijn het sleutels van labels, en from is null als het antwoord geen label had. lead.created, campaign.status_changed en email.sent beginnen ongeveer een minuut nadat de eerste webhook die ze wil ontvangen is aangemaakt; er wordt niets van daarvoor verstuurd. Als je server ver achterloopt, wachten nieuwe email.sent-aanroepen tot hij is bijgewerkt; er gaat er geen verloren.

Lees je de API liever volgens een schema uit, laat elke ronde dan een paar minuten vóór het einde van de vorige beginnen en sla de id's over die je al hebt. Een rij kan net iets later worden opgeslagen dan het tijdstip dat ze draagt, dus een venster dat precies begint waar het vorige eindigde, kan haar missen. Met webhooks heb je dit allemaal niet nodig.

Een webhook aanmaken

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

Het adres moet een openbaar https://-adres zijn. Het antwoord bevat het secret waarmee wordt ondertekend. Het wordt maar één keer getoond, dus bewaar het meteen. Elk account kan maximaal 10 ingeschakelde webhooks hebben en 50 in totaal. Voeg je een adres toe dat je al hebt, dan wijzigt dat die webhook (de nieuwe events, ingeschakeld) en is het antwoord 200 met existing: true en geen nieuw secret.

Een webhook aanmaken vereist het plan Pro of hoger, van jezelf of van een workspace waarvan je teamlid bent, anders krijg je 402 plan_required. Iedere persoon heeft zijn eigen limiet. Een onbekend event geeft 400 invalid_webhook_events, en een 11e ingeschakelde webhook of een 51e in totaal geeft 400 webhook_limit_reached.

AanroepWat het doet
GET /api/v1/webhooksJe webhooks en elk event dat je kunt kiezen
PATCH /api/v1/webhooks/{id}De URL of de events wijzigen, of de webhook uitschakelen met "active": false
DELETE /api/v1/webhooks/{id}De webhook verwijderen
POST /api/v1/webhooks/{id}/testEén ondertekende testaanroep versturen met de voorbeeld-data van een event en "test": true
GET /api/v1/webhooks/{id}/deliveriesRecente aanroepen met hun resultaat en de volgende poging

Wat je server ontvangt

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

Elke aanroep heeft dezelfde vier sleutels: event, delivery_id (een getal dat als tekst wordt verstuurd, hetzelfde als X-Argorant-Delivery), created_at en data. Antwoord binnen een paar seconden met een willekeurige 2xx-status. Doe het trage werk pas nadat je hebt geantwoord. Redirects worden niet gevolgd, gebruik dus het uiteindelijke adres.

Voorbeeldpayloads

Eén volledige body per event, zoals je server die ontvangt. export.ready en list.ready bevatten ook status_api_path (en download_api_path bij exports), oudere paden die blijven bestaan voor bestaande integraties; die zijn hieronder weggelaten. Gebruik status_url en 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"}}

Testaanroepen

POST /api/v1/webhooks/{id}/test verstuurt één ondertekende aanroep met de voorbeeld-data van een van de events van de webhook, hetzelfde als hierboven, plus "test": true, zodat je code een test kan onderscheiden van een echt event. Stuur {"event": "lead.created"} om het event te kiezen; zonder dat wordt het eerste event van de webhook gebruikt. Een event dat de webhook niet ontvangt, geeft 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}}

De handtekening controleren

De handtekening is de HMAC-SHA256 van de ruwe body met je secret. Vergelijk hem voordat je de aanroep vertrouwt. Gebruik de bytes van de body precies zoals ze binnenkwamen, vóór elke JSON-parsing.

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

De ondertekende body bevat delivery_id en created_at, dus geen van beide kan worden gewijzigd zonder de handtekening te breken. Bewaar de delivery-id's die je hebt verwerkt en sla er een over die je al eerder hebt gezien. Zo kan een opnieuw afgespeelde aanroep geen kwaad.

Als je server niet bereikbaar is

Een mislukte aanroep wordt opnieuw geprobeerd na 1 minuut, 5 minuten, 30 minuten, 2 uur en 6 uur, dus tot 6 keer. X-Argorant-Delivery blijft voor elke poging van één event hetzelfde, gebruik het dus om events over te slaan die je al hebt verwerkt. Na 50 mislukte aanroepen op rij wordt de webhook uitgeschakeld; schakel hem weer in met PATCH en "active": true. Een 404 telt niet mee: de aanroep wordt opnieuw geprobeerd zoals hierboven, en de webhook wordt pas uitgeschakeld als je adres 7 dagen lang 404 heeft geantwoord zonder dat er een aanroep doorkwam. Een 410 Gone betekent dat het adres definitief weg is, dus de webhook wordt meteen verwijderd; voeg hem opnieuw toe als je de aanroepen weer wilt ontvangen.

Op deze pagina