Webhooks

Cómo funciona

Un webhook es una dirección HTTPS de tu servidor a la que AtiendeFácil le hace un POST con un JSON cada vez que pasa algo que elegiste: entra un pedido, se aprueba un pago, escribe un cliente, cambia un precio… Así tu sistema se entera al instante sin preguntar a cada rato.

El aviso se prepara en el mismo momento en que se guarda el cambio: si el cambio queda hecho, el aviso existe (aunque el servidor se reinicie), y si el cambio se deshace, el aviso también. Suele llegar en uno o dos segundos.

Configurar un webhook

Lo crea el dueño o alguien del equipo con permiso para editar Ajustes: pega tu dirección, marca los eventos y pulsa Probar. Después te pasa el secreto de firma (whsec_…) para que verifiques los avisos. Los pasos están en Integraciones.

La dirección tiene que cumplir esto:

• Empezar por https://, con un certificado válido, y ser un dominio público: no se aceptan IP, localhost ni direcciones de red interna (tampoco un dominio que resuelva a una).
• Sin usuario ni contraseña dentro de la URL, y de hasta 500 caracteres.
• No redirigir: las redirecciones (3xx) no se siguen y cuentan como fallo.

Un negocio puede tener hasta 5 webhooks, cada uno con sus eventos y su propio secreto. Si dos están suscritos al mismo evento, cada uno recibe su aviso con un id distinto.

Crear el webhook por la API

Además de crearlo a mano en Ajustes → Integraciones, tu sistema puede conectarse solo con su clave de API.

Valen las mismas reglas que en el panel: URL pública con https, eventos del catálogo y el mismo tope de webhooks (409 webhooks_full si ya no caben).

Clave de acceso

Si tu servidor rechaza todo lo que llega sin su clave (un túnel, una pasarela de API, un cortafuegos de aplicación), el dueño puede guardar en el webhook una clave de acceso: una cabecera fija que AtiendeFácil manda en cada aviso, también en el de Probar y en los reintentos. Se pone al crear el webhook o al editarlo, en la sección Clave de acceso, en el panel y en la app.

• Viaja en la cabecera x-api-key si no se elige otra. El nombre de la cabecera lleva solo letras, números y guiones (hasta 64 caracteres) y se manda en minúsculas.
• No puede ser una cabecera que ya usa el aviso: host, content-type, content-length, user-agent, connection, transfer-encoding, cookie ni ninguna que empiece por x-atiendefacil-.
• La clave admite hasta 500 caracteres, sin saltos de línea, acentos ni emojis. Se manda tal cual se pegó: si tu servidor espera un prefijo (Bearer …), va dentro de la clave.
• Después de guardarla no se vuelve a mostrar: en pantalla solo se ve en qué cabecera viaja. Se puede reemplazar por otra o quitar.

Eventos

Hay 32 eventos. El nombre del evento es el contrato: no se renombra, y con el tiempo pueden añadirse otros.

• order.created sale cuando el pedido deja de ser carrito, no mientras el bot lo arma.
• message.received sale solo con lo que escribe el cliente. Lo que le manda el negocio —el asistente, una persona del equipo o tu integración— sale como message.sent, en cuanto queda en el chat: no espera a que WhatsApp confirme la entrega. Un mensaje que no se pudo mandar por estar fuera de la ventana de 24 horas no avisa. Los mensajes que tú mandas por la API también llegan: reconócelos por el id que te devolvió POST /messages para no contestarte a ti mismo.
• product.updated sale también cuando una venta baja el stock.
• rate.updated no sale cuando el BCV publica tasa nueva: solo cuando el negocio cambia su modo, su tasa manual o su moneda base.
• whatsapp.disconnected sale solo cuando la sesión se cerró y hay que volver a vincular el número. Las reconexiones de rutina, que pasan varias veces al día y se arreglan solas, no avisan. whatsapp.connected sale al volver a vincularlo (o al vincular un número nuevo).
• account.balance_low sale una vez cuando el saldo baja del aviso de saldo bajo (ver Saldo y facturación), y no se repite hasta que el negocio recarga y vuelve a bajar.
• conversation.needs_agent no sale con la espera de la cotización del envío: esa tiene su propio evento, order.delivery_quote_needed.
• customer.lookup es el único que no es un aviso sino una consulta: se espera tu respuesta y se usa. Tiene sus propias reglas (ver Consultar un cliente en tu sistema).

Eventos que piden una acción

La mayoría de eventos solo informan. Estos, en cambio, dicen que algo está esperando a una persona: son los mismos avisos que le llegan al dueño por WhatsApp o en la app, y tu sistema puede resolverlos (o avisar a quien toque).

Una escalada (conversation.needs_agent) que nadie atiende no dura para siempre: si pasan 12 horas y el cliente vuelve a escribir, el bot retoma la conversación solo y sale conversation.bot_resumed. Un chat tomado a mano (conversation.taken_over), en cambio, no caduca: sigue así hasta que alguien lo devuelve.

Consultar un cliente en tu sistema

Si el negocio ya tiene a sus clientes en otro sistema (un ERP, un punto de venta, un CRM), customer.lookup evita que el asistente les pida datos que ya están ahí. Cuando escribe alguien a quien le falta el nombre o la cédula, AtiendeFácil le pregunta a tu servidor por su teléfono antes de contestarle. Si lo conoces, respondes con sus datos: quedan en su ficha, el saludo ya va por su nombre y el asistente no se los pide.

{
  "id": "2e3f4a5b-6c7d-4e8f-9a0b-1c2d3e4f5a6b",
  "type": "customer.lookup",
  "created_at": "2026-10-11T14:02:07.512Z",
  "company_id": "0f8e7d6c-5b4a-4392-8170-6f5e4d3c2b1a",
  "data": {
    "object": {
      "id": "c4d5e6f7-a8b9-4c0d-9e1f-2a3b4c5d6e7f",
      "object": "customer",
      "name": "Mari 🌸",
      "phone": "584140000000",
      "id_document": null,
      "address": null,
      "notes": null,
      "name_confirmed": false,
      "bot_muted": false,
      "created_at": "2026-10-11T14:02:07.101Z",
      "updated_at": "2026-10-11T14:02:07.101Z"
    }
  }
}

HTTP/1.1 200 OK
Content-Type: application/json

{
  "customer": {
    "name": "María Pérez",
    "id_document": "V-00000000",
    "address": "Av. Principal de Los Palos Grandes, casa 12"
  }
}

HTTP/1.1 200 OK
Content-Type: application/json

{ "customer": null }

// Dentro del receptor de arriba, después de verificar la firma:
if (event.type === "customer.lookup") {
  const phone = event.data.object.phone;            // "584140000000"
  const row = await erp.findCustomerByPhone(phone);  // tu consulta, rápida
  return res.json({
    customer: row
      ? { name: row.fullName, id_document: row.taxId, address: row.address }
      : null,
  });
}

El cuerpo del aviso

Todos los avisos tienen la misma forma:

{
  "id": "0c6f1e2d-3a4b-4c5d-8e6f-7a8b9c0d1e2f",
  "type": "order.status_changed",
  "created_at": "2026-09-29T18:03:40.130Z",
  "company_id": "0f8e7d6c-5b4a-4392-8170-6f5e4d3c2b1a",
  "data": {
    "object": { "id": "5b7c2e1a-…", "object": "order", "status": "preparing", … },
    "status": "preparing",
    "previous_status": "confirmed"
  }
}

Ejemplos por evento

El data de cada evento (el objeto va abreviado con …; completo es igual que en la API).

{
  "object": { "id": "5b7c2e1a-…", "object": "order", "number": "4A1B2C", "status": "pending_payment", … },
  "status": "pending_payment"
}

{
  "object": { "id": "5b7c2e1a-…", "object": "order", "number": "4A1B2C", "status": "preparing", … },
  "status": "preparing",
  "previous_status": "confirmed"
}

{
  "object": { "id": "5b7c2e1a-"fulfillment": "delivery", "delivery_fee": "0.00", …", "object": "order", "number": "4A1B2C", "status": "draft", … },
  "conversation_id": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b"
}

{
  "object": { "id": "5b7c2e1a-…", "object": "order", "number": "4A1B2C", "status": "out_for_delivery", … },
  "assigned_to": "b3c4d5e6-f7a8-4b9c-8d0e-1f2a3b4c5d6e",
  "previous_assigned_to": null
}

{
  "object": { "id": "7a8b9c0d-…", "object": "payment", "status": "pending", "order_id": "5b7c2e1a-…", … },
  "status": "pending"
}

{
  "object": { "id": "7a8b9c0d-…", "object": "payment", "status": "approved", "order_id": "5b7c2e1a-…", … },
  "status": "approved",
  "previous_status": "pending"
}

{
  "object": { "id": "7a8b9c0d-…", "object": "payment", "status": "review", "order_id": "5b7c2e1a-…", … },
  "status": "review"
}

{
  "object": { "id": "d6e7f8a9-…", "object": "appointment", "status": "requested", "starts_at": "2026-10-02T16:00:00.000Z", … },
  "status": "requested"
}

{
  "object": { "id": "d6e7f8a9-…", "object": "appointment", "status": "confirmed", "starts_at": "2026-10-02T16:00:00.000Z", … },
  "status": "confirmed",
  "previous_status": "requested"
}

{
  "object": { "id": "d6e7f8a9-…", "object": "appointment", "status": "confirmed", "starts_at": "2026-10-02T16:00:00.000Z", … },
  "status": "confirmed",
  "previous_starts_at": "2026-10-02T15:00:00+00:00"
}

{
  "object": { "id": "d6e7f8a9-b0c1-4d2e-9f3a-4b5c6d7e8f9a", "object": "appointment", "deleted": true }
}

{
  "object": { "id": "c4d5e6f7-…", "object": "customer", "name": null, "phone": "584140000000", … }
}

{
  "object": { "id": "c4d5e6f7-…", "object": "customer", "name": "María Pérez", "phone": "584140000000", … },
  "changes": ["address", "notes"]
}

{
  "object": { "id": "c4d5e6f7-a8b9-4c0d-9e1f-2a3b4c5d6e7f", "object": "customer", "deleted": true },
  "phone": "584140000000",
  "name": "María Pérez"
}

{
  "object": { "id": "c4d5e6f7-…", "object": "customer", "name": "Mari 🌸", "phone": "584140000000", "id_document": null, "name_confirmed": false, … }
}

{
  "object": {
    "id": "f5a6b7c8-…",
    "object": "message",
    "conversation_id": "e1f2a3b4-…",
    "direction": "inbound",
    "sender": "customer",
    "type": "text",
    "text": "Buenas, ¿tienen pizza de pepperoni?",
    "location": null,
    "file": null,
    "has_media": false,
    "customer": { "id": "c4d5e6f7-…", "name": "María Pérez", "phone": "584140000000" },
    "created_at": "2026-09-29T18:40:12.551Z"
  }
}

{
  "object": {
    "id": "a6b7c8d9-…",
    "object": "message",
    "conversation_id": "e1f2a3b4-…",
    "direction": "outbound",
    "sender": "assistant",
    "type": "text",
    "text": "¡Hola, María! Sí, la de pepperoni está en $10. ¿Te anoto una?",
    "location": null,
    "file": null,
    "has_media": false,
    "customer": { "id": "c4d5e6f7-…", "name": "María Pérez", "phone": "584140000000" },
    "created_at": "2026-09-29T18:40:19.204Z"
  },
  "sender": "assistant"
}

{
  "object": { "id": "f8a9b0c1-…", "object": "ride", "status": "requested", "driver": null, … },
  "status": "requested"
}

{
  "object": { "id": "f8a9b0c1-…", "object": "ride", "status": "accepted", "driver": { "id": "…", "name": "Pedro" }, … },
  "status": "accepted",
  "previous_status": "requested"
}

{
  "object": { "id": "f8a9b0c1-…", "object": "ride", "status": "requested", "driver": null, … },
  "status": "requested",
  "reason": "no_drivers_left"
}

{
  "object": { "id": "a1b2c3d4-…", "object": "product", "external_id": "SKU-0042", "barcode": "7591234567895", "price": "10.00", "stock": 11, "deleted_at": null, … },
  "source": "api:9f1c2b3a-4d5e-4f60-8a7b-1c2d3e4f5a6b"
}

{
  "object": { "id": "a1b2c3d4-…", "object": "product", "external_id": "SKU-0042", "barcode": "7591234567895", "price": "10.00", "stock": 11, "deleted_at": null, … },
  "changes": ["price", "stock"],
  "previous_stock": 12,
  "source": "api:9f1c2b3a-4d5e-4f60-8a7b-1c2d3e4f5a6b"
}

{
  "object": { "id": "a1b2c3d4-…", "object": "product", "external_id": "SKU-0042", "barcode": "7591234567895", "price": "10.00", "stock": 11, "deleted_at": "2026-09-29T20:15:00.000Z", … }
}

{
  "object": { "object": "rate", "mode": "manual", "manual_rate": "38.5000", "base_currency": "USD" },
  "mode": "manual",
  "manual_rate": 38.5000,
  "base_currency": "USD",
  "previous_mode": "bcv",
  "previous_manual_rate": null,
  "source": "api:9f1c2b3a-4d5e-4f60-8a7b-1c2d3e4f5a6b"
}

{
  "object": { "id": "e1f2a3b4-…", "object": "conversation", "needs_agent": true, "taken_over": false, "customer": { "id": "c4d5e6f7-…", … }, … },
  "reason": "¿Hacen tortas por encargo para 40 personas?"
}

{
  "object": { "id": "e1f2a3b4-…", "object": "conversation", "needs_agent": false, "taken_over": true, "customer": { "id": "c4d5e6f7-…", … }, … }
}

{
  "object": { "id": "e1f2a3b4-…", "object": "conversation", "needs_agent": false, "taken_over": false, "customer": { "id": "c4d5e6f7-…", … }, … }
}

{
  "object": {
    "object": "account",
    "bot": { "paused": true, "pause_source": "manual", "pause_reason": null },
    "whatsapp": { "status": "connected", "phone": "584140000000", "channel": "qr" },
    "balance": { "tokens": 184250, "low": false }
  },
  "pause_source": "manual",
  "reason": null
}

{
  "object": {
    "object": "account",
    "bot": { "paused": false, "pause_source": null, "pause_reason": null },
    "whatsapp": { "status": "connected", "phone": "584140000000", "channel": "qr" },
    "balance": { "tokens": 184250, "low": false }
  },
  "previous_pause_source": "risk"
}

{
  "object": {
    "object": "account",
    "bot": { "paused": false, "pause_source": null, "pause_reason": null },
    "whatsapp": { "status": "logout", "phone": null, "channel": "qr" },
    "balance": { "tokens": 184250, "low": false }
  },
  "status": "logout",
  "previous_status": "connected",
  "phone": "584140000000"
}

{
  "object": {
    "object": "account",
    "bot": { "paused": false, "pause_source": null, "pause_reason": null },
    "whatsapp": { "status": "connected", "phone": "584140000000", "channel": "qr" },
    "balance": { "tokens": 184250, "low": false }
  },
  "status": "connected",
  "phone": "584140000000"
}

{
  "object": {
    "object": "account",
    "bot": { "paused": false, "pause_source": null, "pause_reason": null },
    "whatsapp": { "status": "connected", "phone": "584140000000", "channel": "qr" },
    "balance": { "tokens": 49850, "low": true }
  },
  "balance": 49850
}

{
  "id": "1d2e3f4a-5b6c-4d7e-8f9a-0b1c2d3e4f5a",
  "type": "ping",
  "created_at": "2026-09-29T18:30:00.000Z",
  "company_id": "0f8e7d6c-5b4a-4392-8170-6f5e4d3c2b1a",
  "data": {
    "object": { "message": "Prueba desde AtiendeFácil. Si ves esto, tu webhook funciona." }
  }
}

Cabeceras

POST /webhooks/atiendefacil HTTP/1.1
Content-Type: application/json
User-Agent: AtiendeFacil-Webhooks/1.0
X-AtiendeFacil-Event: order.status_changed
X-AtiendeFacil-Delivery: 0c6f1e2d-3a4b-4c5d-8e6f-7a8b9c0d1e2f
X-AtiendeFacil-Signature: t=1759169020,v1=5f2b9c…e41a
x-api-key: la-clave-de-tu-servidor

Verificar la firma

Cualquiera que conozca tu dirección podría mandarte un POST. La firma te asegura que el aviso lo mandó AtiendeFácil y que nadie lo tocó por el camino:

1. Lee la cabecera

   X-AtiendeFacil-Signature: t=1759169020,v1=5f2b…. t es la hora del envío en segundos Unix; v1, la firma en hexadecimal.

2. Calcula la tuya

   HMAC-SHA256(secreto, "<t>.<cuerpo crudo>") en hexadecimal: el valor de t, un punto y el cuerpo tal como llegó.

3. Compara y mira la hora

   Compara las dos firmas con una comparación de tiempo constante y rechaza el aviso si t tiene más de 5 minutos: así un aviso capturado no sirve para repetirlo días después. Cada intento se firma de nuevo, con su propio t.

import crypto from "node:crypto";

function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${parts.t}.${rawBody}`)
    .digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
  const a = Buffer.from(expected);
  const b = Buffer.from(parts.v1 ?? "");
  return fresh && a.length === b.length && crypto.timingSafeEqual(a, b);
}

function verify($rawBody, $header, $secret) {
  parse_str(str_replace(',', '&', $header), $p);
  $expected = hash_hmac('sha256', $p['t'] . '.' . $rawBody, $secret);
  return abs(time() - (int)$p['t']) < 300 && hash_equals($expected, $p['v1'] ?? '');
}

// $rawBody = file_get_contents('php://input');
// $header  = $_SERVER['HTTP_X_ATIENDEFACIL_SIGNATURE'] ?? '';

import hmac, hashlib, time

def verify(raw_body: bytes, header: str, secret: str) -> bool:
    p = dict(x.split("=", 1) for x in header.split(","))
    expected = hmac.new(secret.encode(), f"{p['t']}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return abs(time.time() - int(p["t"])) < 300 and hmac.compare_digest(expected, p.get("v1", ""))

Si el secreto se filtra, el dueño pulsa Cambiar secreto en Integraciones: el anterior deja de valer en el momento, así que ten listo el nuevo.

Responder rápido

• Responde con cualquier 2xx en menos de 10 segundos. Lo que respondas en el cuerpo no se lee. La excepción es customer.lookup: ahí el cuerpo es la respuesta y el plazo son 4 segundos.
• Si tienes trabajo pesado (facturar, llamar a otro sistema), responde primero y procésalo después, en una cola.
• Cualquier otra cosa cuenta como fallo y se reintenta: un 4xx, un 5xx, una redirección, pasarse de 10 segundos, no poder conectar o un certificado inválido.

Un receptor completo en Node.js con Express:

import express from "express";

const app = express();
const SECRET = process.env.ATIENDEFACIL_WEBHOOK_SECRET; // whsec_…
const seen = new Set(); // en producción: una tabla con índice único

// express.raw: el cuerpo llega tal cual, que es sobre lo que se firma.
app.post("/webhooks/atiendefacil", express.raw({ type: "application/json" }), (req, res) => {
  const raw = req.body.toString("utf8");
  if (!verify(raw, req.get("X-AtiendeFacil-Signature") ?? "", SECRET)) {
    return res.sendStatus(401);
  }
  const event = JSON.parse(raw);
  res.sendStatus(200); // responde YA; el trabajo va después

  if (seen.has(event.id)) return; // repetido: ya se procesó
  seen.add(event.id);
  queueMicrotask(() => handle(event)); // o a tu cola de trabajos
});

app.listen(3000);

Reintentos

Si un envío falla, se vuelve a intentar solo, esperando cada vez más, hasta 8 intentos en unas 11 horas:

En Historial de envíos (Integraciones) se ve cada aviso de los últimos 30 días: su estado, cuántos intentos lleva, qué respondió tu servidor y el cuerpo exacto que se mandó. Desde ahí, Reenviar vuelve a mandar un aviso con todos sus intentos.

Idempotencia, orden y tus propios cambios

• Puede llegar repetido. Si tu servidor procesó el aviso pero la respuesta no llegó a tiempo, se reintenta. Guarda el id (o X-AtiendeFacil-Delivery) y descarta los que ya viste. Reenviar desde el historial manda el mismo id.
• Puede llegar desordenado. Los avisos salen en paralelo y los reintentos se intercalan. Compara el updated_at del objeto con el que ya tienes y quédate con el más nuevo; si necesitas el estado exacto, pídelo a la API.
• Tus propios cambios también avisan. Lo que tu integración cambia por la API dispara webhooks como cualquier otro cambio. Cuando el cambio va marcado con tu clave, el aviso trae data.source = "api:<id de la clave>". Compáralo con el api_key.id de GET /me y, si es el tuyo, ignóralo: así tu sistema no vuelve a mandar lo que acaba de recibir y no entra en bucle. Lo marcan el catálogo, la tasa, editar un cliente y tomar o devolver un chat (product.*, rate.updated, customer.updated, conversation.taken_over, conversation.bot_resumed). Los datos que entran por tu respuesta a customer.lookup llegan con data.source = "lookup:<id del webhook>". Lo que pasa por los mismos procesos que el panel —cambiar el estado de un pedido, aprobar o registrar pagos, cotizar el envío— todavía llega sin source: ahí compara con lo que ya tienes antes de volver a escribir.

Si el webhook se apaga solo

Si 10 avisos seguidos agotan todos sus intentos, el webhook se apaga solo y en Integraciones sale el motivo. Un aviso entregado pone la cuenta a cero.

• Mientras está apagado, no se guardan avisos: lo que pase en ese tiempo no te llegará después. Lo que ya estaba esperando reintento queda como fallido.
• Cuando tu servidor esté arreglado, el dueño lo vuelve a encender con el interruptor (la cuenta de fallos vuelve a cero). Para recuperar lo que te perdiste, pide a la API lo que cambió desde entonces con updated_after (ver sincronización incremental), o reenvía desde el historial los que quedaron fallidos.

Probar en tu computadora

AtiendeFácil no puede llamar a localhost. Para probar tu receptor mientras lo programas, expónlo con un túnel HTTPS que te dé un dominio público, por ejemplo ngrok http 3000 o cloudflared tunnel --url http://localhost:3000, y usa esa dirección en el webhook.

1. Crea el webhook con la dirección del túnel

   Marca solo los eventos que vas a probar.

2. Pulsa Probar

   Llega un ping firmado y en pantalla ves si tu servidor respondió bien o por qué falló («No respondió en 10 segundos», «Respondió 401»…).

3. Provoca un evento de verdad

   Cambia un pedido de estado desde el panel o un precio del catálogo, y mira el aviso en tu consola y en el Historial de envíos.

4. Usa Reenviar para repetir

   Vuelve a mandar el mismo aviso las veces que haga falta mientras ajustas tu código.

Preguntas frecuentes