ArgorantDocs

Webhooks

Recibe una llamada firmada en tu servidor cuando llega una respuesta, alguien muestra interés, rebota un correo o una lista o una exportación está lista. Incluido desde el plan Pro.

Eventos

EventoCuándo se disparaQué contiene data
reply.receivedUna persona respondió a una de tus campañas. Los avisos automáticos de ausencia quedan fuera, salvo que tu espacio de trabajo haya ocultado su etiqueta Fuera de la oficina. También se dispara cuando cambias una respuesta de Fuera de la oficina a otra etiquetaclassification, lead_email, campaign_id, subject, snippet, reply_id, lead_id, received_at
reply.positiveLe pusiste a una respuesta la etiqueta Interesado o Solicitud de reunión, en la app o con POST /api/v1/inbox/{id}/classify. Solo se dispara cuando cambia la etiqueta, así que una respuesta envía reply.received cuando llega y reply.positive cuando la etiquetasclassification, lead_email, campaign_id, subject, snippet, reply_id, lead_id, received_at
email.bouncedUn correo de campaña rebotó. No se envía si esa persona había respondido anteslead_email, campaign_id, subject
email.unsubscribedAlguien usó el enlace para darse de baja, o le pusiste a su respuesta la etiqueta Darse de bajaclassification, lead_email, campaign_id, subject, snippet, y source para el enlace de baja, o reply_id, lead_id y received_at cuando vino de una etiqueta
campaign.pausedArgorant pausó una campaña en marcha: se agotaron los correos de campaña de tu plan (o terminó la prueba o el plan), o la campaña se pausó sola por rebotes o buzones desconectados. Tu propia pausa no envía nadacampaign_id, campaign_name, reason, message, y campaign_emails (plan) o metrics y url (pausa automática)
campaign.resumedVuelve a haber correos de campaña disponibles (un mes nuevo o un plan mayor), así que una campaña pausada por el plan vuelve a enviar. Tu propio lanzamiento no envía nadacampaign_id, campaign_name, reason, message, campaign_emails
export.readyTerminó una exportación. No se envía si fallójob_id, status, total_rows, verified_rows, status_url, download_url, status_api_path, download_api_path
list.readyUna lista terminó de llenarse, también después de añadir más personas. No se envía si el llenado fallólist_id, list_name, job_id, status, total_items, note, status_url, status_api_path
verification.completedTerminó una comprobación de un solo correo hecha con una clave de APIemail, status, deliverable, is_role_based, is_free, is_disposable
segment.new_matchesUna lista de búsqueda guardada tiene más personas que coinciden que la última vez que se contó. Las listas se revisan más o menos cada 30 minutoslist_id, list_name, previous_total, current_total, new_matches
lead.createdSe añadieron personas a una campaña, en la app, a través de la API, desde un archivo, desde una lista o con un traslado. Una entrega por cada lote que recibió la campaña, así que una importación grande llega en varias entregas. Las personas que se quitaron antes de que saliera la entrega quedan fueracampaign_id, campaign_name, count, leads, cada uno con lead_id, email, first_name, last_name, company, title, status, custom_fields, added_at
campaign.status_changedCambió el estado de una campaña, por tu parte o por parte de Argorant: un lanzamiento, una pausa, una detención o un archivado, o una pausa por correos de campaña, rebotes o buzones desconectados. También se dispara junto a campaign.paused y campaign.resumedcampaign_id, campaign_name, from, to, changed_at
email.sentSalieron correos de campaña. Llega en aproximadamente un minuto tras el envío, una entrega por campaña con hasta 100 correoscampaign_id, campaign_name, count, emails, cada uno con email_id, lead_id, lead_email, subject, step, mailbox, sent_at
reply.label_changedAlguien puso o cambió la etiqueta de una respuesta, en la bandeja de entrada de la app o con POST /api/v1/inbox/{id}/classify. Volver a poner la misma etiqueta no envía nadareply_id, lead_id, lead_email, campaign_id, subject, from, to, changed_at

Los eventos de campaña van a los webhooks del propietario del espacio de trabajo y de cada miembro activo del equipo, para que cada persona pueda dirigirlos a sus propias herramientas. Las exportaciones, las listas y las comprobaciones van a los webhooks de la persona que las inició. Las nuevas coincidencias van a los webhooks del propietario de la lista.

En los eventos de respuesta, classification es null para una respuesta que acaba de llegar, y es la clave de la etiqueta en cuanto alguien pone una, por ejemplo positive o meeting_request. subject contiene hasta 300 caracteres y snippet hasta 500 caracteres de texto plano. reply_id es la respuesta, lead_id la persona en la campaña y received_at el momento en que llegó la respuesta. El reason de campaign.paused es campaign_email_allowance cuando el plan pausó la campaña, y auto_pause_bounce_rate, auto_pause_inboxes_offline o auto_pause cuando se pausó sola. campaign_emails.reason indica por qué se acabaron los correos (allowance_used, trial_ended, plan_ended o confirm_email) y está vacío en campaign.resumed.

from y to de campaign.status_changed son draft, active, paused, completed o archived. En reply.label_changed son claves de etiqueta, y from es null cuando la respuesta no tenía etiqueta. lead.created, campaign.status_changed y email.sent empiezan más o menos un minuto después de crear el primer webhook que los pide; no se envía nada anterior. Cuando tu servidor se queda muy atrás, las nuevas llamadas email.sent esperan hasta que se ponga al día; no se pierde ninguna.

Si en lugar de eso lees la API de forma programada, empieza cada lectura unos minutos antes del final de la anterior y omite los ids que ya tienes. Una fila puede guardarse un momento después de la hora que lleva, así que una ventana que empieza justo donde terminó la anterior puede perderla. Con webhooks no necesitas nada de esto.

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

La dirección tiene que ser una dirección pública https://. La respuesta contiene el secret de firma. Solo se muestra una vez, así que guárdalo ahora. Cada cuenta puede tener hasta 10 webhooks activados y 50 en total. Añadir una dirección que ya tienes modifica ese webhook (los eventos nuevos, activado) y responde 200 con existing: true y sin secreto nuevo.

Crear un webhook requiere el plan Pro o superior, el tuyo o el de un espacio de trabajo del que seas miembro del equipo; si no, recibes 402 plan_required. Cada persona tiene su propio límite. Un evento desconocido responde 400 invalid_webhook_events, y un 11.º webhook activado o un 51.º en total, 400 webhook_limit_reached.

LlamadaQué hace
GET /api/v1/webhooksTus webhooks y todos los eventos que puedes elegir
PATCH /api/v1/webhooks/{id}Cambia la URL o los eventos, o lo desactiva con "active": false
DELETE /api/v1/webhooks/{id}Lo elimina
POST /api/v1/webhooks/{id}/testEnvía una llamada de prueba firmada con el data de ejemplo de un evento y "test": true
GET /api/v1/webhooks/{id}/deliveriesLas llamadas recientes con su resultado y el próximo intento

Qué recibe tu servidor

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

Todas las llamadas tienen las mismas cuatro claves: event, delivery_id (un número enviado como texto, igual que X-Argorant-Delivery), created_at y data. Responde con cualquier estado 2xx en pocos segundos. Haz el trabajo lento después de responder. Las redirecciones no se siguen, así que usa la dirección final.

Ejemplos de payloads

Un cuerpo completo por evento, tal como lo recibe tu servidor. export.ready y list.ready también llevan status_api_path (y download_api_path en las exportaciones), rutas antiguas que se mantienen para integraciones existentes; abajo se omiten. Usa status_url y 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"}}

Llamadas de prueba

POST /api/v1/webhooks/{id}/test envía una llamada firmada con el data de ejemplo de uno de los eventos del webhook, el mismo que arriba, más "test": true, para que tu código pueda distinguir una prueba de un evento real. Envía {"event": "lead.created"} para elegir el evento; sin él se usa el primer evento del webhook. Un evento que el webhook no recibe responde 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}}

Comprueba la firma

La firma es el HMAC-SHA256 del cuerpo sin procesar con tu secreto. Compárala antes de fiarte de la llamada. Usa los bytes del cuerpo exactamente como llegaron, antes de cualquier parseo de 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);
}

El cuerpo firmado contiene delivery_id y created_at, así que ninguno de los dos se puede cambiar sin romper la firma. Guarda los ids de entrega que ya procesaste y omite los que ya hayas visto. Así una llamada reenviada no causa ningún daño.

Cuando tu servidor no responde

Una llamada que falla se reintenta al cabo de 1 minuto, 5 minutos, 30 minutos, 2 horas y 6 horas, así que hasta 6 veces. X-Argorant-Delivery es el mismo en todos los intentos de un evento, así que úsalo para omitir los eventos que ya procesaste. Tras 50 llamadas fallidas seguidas, el webhook se desactiva; vuelve a activarlo con PATCH y "active": true. Un 404 no cuenta: la llamada se reintenta como arriba, y el webhook solo se desactiva cuando tu dirección lleva 7 días respondiendo 404 sin que pase ninguna llamada. Un 410 Gone significa que la dirección ya no existe, así que el webhook se elimina al momento; vuelve a añadirlo cuando quieras recibir las llamadas de nuevo.

En esta página