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
| Evento | Cuándo se dispara | Qué contiene data |
|---|---|---|
reply.received | Una 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 etiqueta | classification, lead_email, campaign_id, subject, snippet, reply_id, lead_id, received_at |
reply.positive | Le 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 etiquetas | classification, lead_email, campaign_id, subject, snippet, reply_id, lead_id, received_at |
email.bounced | Un correo de campaña rebotó. No se envía si esa persona había respondido antes | lead_email, campaign_id, subject |
email.unsubscribed | Alguien usó el enlace para darse de baja, o le pusiste a su respuesta la etiqueta Darse de baja | classification, 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.paused | Argorant 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 nada | campaign_id, campaign_name, reason, message, y campaign_emails (plan) o metrics y url (pausa automática) |
campaign.resumed | Vuelve 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 nada | campaign_id, campaign_name, reason, message, campaign_emails |
export.ready | Terminó 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.ready | Una 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.completed | Terminó una comprobación de un solo correo hecha con una clave de API | email, status, deliverable, is_role_based, is_free, is_disposable |
segment.new_matches | Una 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 minutos | list_id, list_name, previous_total, current_total, new_matches |
lead.created | Se 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 fuera | campaign_id, campaign_name, count, leads, cada uno con lead_id, email, first_name, last_name, company, title, status, custom_fields, added_at |
campaign.status_changed | Cambió 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.resumed | campaign_id, campaign_name, from, to, changed_at |
email.sent | Salieron correos de campaña. Llega en aproximadamente un minuto tras el envío, una entrega por campaña con hasta 100 correos | campaign_id, campaign_name, count, emails, cada uno con email_id, lead_id, lead_email, subject, step, mailbox, sent_at |
reply.label_changed | Alguien 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 nada | reply_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
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.
| Llamada | Qué hace |
|---|---|
GET /api/v1/webhooks | Tus 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}/test | Envía una llamada de prueba firmada con el data de ejemplo de un evento y "test": true |
GET /api/v1/webhooks/{id}/deliveries | Las llamadas recientes con su resultado y el próximo intento |
Qué recibe tu servidor
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
{"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"}}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.
{"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.
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);
}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.
Etiquetas de buzones
Etiqueta los buzones nuevos al pedirlos, y etiqueta o firma cientos de buzones existentes en un solo paso, por ejemplo todos los buzones de un pedido.
Enviar personas a tus otras herramientas
Envía una exportación a la herramienta de envío que ya usas, en tu propia cuenta. Una lista se envía como su exportación. Incluido desde el plan Pro.