Order Webhooks

Qué hacen los webhooks

Un webhook es una forma de que DabDash le avise a tus propios sistemas — tu CRM, tu herramienta de automatización, tu servidor personalizado — en el momento exacto en que sucede algo en tu tienda. Cuando un cliente realiza un nuevo pedido, DabDash envía una breve solicitud HTTPS a una URL que tú indiques. Tu sistema lee el pedido y hace lo que quieras con él: agregarlo a un embudo de CRM, enviar un enlace de pago, iniciar un envío de entrega, notificar a un canal de Slack.

Por ahora DabDash envía un solo evento — order.created — en el instante en que se realiza un pedido. El pedido está en estado pendiente en ese momento. Otros cambios de estado no disparan un webhook (todavía).

URL del endpoint

Esta es la URL a la que DabDash hará POST de cada nuevo pedido. Debe ser:

• Solo HTTPS — las URLs http:// son rechazadas.
• Accesible públicamente — bloqueamos rangos de IP privadas (todo en 10.x, 172.16-31.x, 192.168.x, 127.x, enlace local). Tu CRM debe estar en internet público.
• Estable — si tu URL cambia, actualízala aquí. No reintentamos entregas fallidas más allá de 4 intentos.

Interruptor Activo

Desactívalo para pausar la entrega sin perder tu configuración. Cuando el interruptor está apagado, no se envían eventos. El mismo interruptor se refleja en la tarjeta del método de pago Webhook en Configuración › Métodos de Pago — apagar uno apaga el otro también.

El secreto de firma

Cada solicitud que DabDash envía a tu endpoint incluye un encabezado llamado X-DabDash-Signature. Este encabezado contiene un HMAC-SHA256 de todo el cuerpo de la solicitud, calculado usando tu secreto. Tu servidor debe:

1. Leer el cuerpo crudo de la solicitud antes de parsear JSON.
2. Calcular sha256=HMAC-SHA256(cuerpo, secreto).
3. Comparar el valor calculado con el encabezado X-DabDash-Signature usando una comparación de tiempo constante.
4. Rechazar la solicitud si los valores no coinciden — eso significa que alguien que no es DabDash la envió.

Puedes rotar el secreto en cualquier momento. El secreto antiguo deja de funcionar inmediatamente — no después de un retraso — así que asegúrate de que tu servidor esté usando el nuevo valor antes de presionar el botón de rotar.

Enviar una carga de prueba

Una vez que hayas guardado una URL y tu endpoint esté en línea, haz clic en Probar webhook para disparar una carga sintética de order.created a tu endpoint. La carga está firmada con tu secreto actual — ideal para confirmar que tu código de verificación de firma funciona antes de que llegue un pedido real de un cliente.

El order_number de la carga sintética es TEST-PING y el cuerpo incluye "test": true para que tu sistema descendente pueda saltarlo.

Encabezados personalizados (Avanzado)

Haz clic en Avanzado para revelar la sección de encabezados personalizados. Algunos CRMs requieren encabezados adicionales para aceptar solicitudes — por ejemplo, un token Authorization: Bearer ..., un identificador de inquilino como X-Shop-Id: 42, o una clave API fija. Agrega hasta 20 pares nombre/valor; se envían con cada solicitud webhook.

Algunos nombres de encabezados están reservados y son rechazados: Host, Content-Type, Content-Length, y cualquier encabezado que comience con X-DabDash- — DabDash controla esos.

Qué hay en la carga

El cuerpo es JSON. Campos de nivel superior:

• event — siempre order.created por ahora.
• timestamp — segundos Unix, cuando se preparó el webhook.
• tenant — { id, slug, name }, identificando tu tienda.
• order — { id, order_number, status, payment_method, subtotal_cents, total_cents, currency, customer, items, created_at }.
• test — solo presente (true) para pings de prueba.

Confiabilidad y reintentos

DabDash reintenta entregas fallidas con retroceso exponencial: 4 intentos en total, con retrasos de 1 min, 5 min y 15 min entre ellos. Reintentamos en errores 5xx del servidor y fallos de conexión, pero no en respuestas 4xx — un 4xx significa que tu endpoint aceptó la solicitud pero la rechazó como entrada inválida, lo cual es un problema de configuración, no un fallo transitorio.

Después del fallo final, el pedido continúa normalmente — la entrega del webhook no bloquea el checkout. El fallo aparece en la página de detalle del pedido bajo Actividad de pago como "Notificación al CRM fallida".