Webhooks

Descripción General

Los webhooks permiten que tu aplicación reciba notificaciones HTTP POST cuando ocurren eventos en una tienda Whatalo. En lugar de hacer polling a la API, tu servidor recibe datos automáticamente.

Cómo Funcionan los Webhooks

1. Ocurre un evento (ej. nuevo pedido realizado)
2. Whatalo envía un POST request a tu URL registrada
3. Tu servidor procesa el payload y devuelve 2xx
4. Si la entrega falla, Whatalo reintenta con backoff exponencial

Gestión de Endpoints de Webhooks

Listar Webhooks

GET /v1/webhooks

Scope requerido: read:webhooks

Crear Webhook

POST /v1/webhooks

{
  "url": "https://your-server.com/webhooks/whatalo",
  "events": ["order.created", "order.updated"]
}

Campo	Tipo	Requerido	Descripción
`url`	string	Sí	URL del endpoint HTTPS (debe ser HTTPS)
`events`	string[]	Sí	Tipos de eventos a suscribir
`secret`	string	No	Secret de firma personalizado (se genera automáticamente si se omite)

Las URLs de webhooks deben usar HTTPS. Los endpoints HTTP son rechazados.

Scope requerido: write:webhooks

Actualizar Webhook

PATCH /v1/webhooks/:id

Scope requerido: write:webhooks

Eliminar Webhook

DELETE /v1/webhooks/:id

Scope requerido: write:webhooks

Tipos de Eventos

Evento	Disparador
`order.created`	Nuevo pedido realizado
`order.updated`	Estado o datos del pedido cambiaron
`product.created`	Nuevo producto creado
`product.updated`	Datos del producto cambiaron
`product.deleted`	Producto eliminado
`customer.created`	Nuevo cliente registrado
`customer.updated`	Datos del cliente cambiaron

Payload del Webhook

Todos los payloads de webhooks siguen esta estructura:

{
  "event": "order.created",
  "timestamp": "2026-03-01T15:00:00Z",
  "data": {
    "id": "ord_abc123",
    "order_number": 1042,
    "order_status": "pending",
    "total": 8997
  }
}

Seguridad de Webhooks

Cada entrega de webhook incluye un header X-Whatalo-Signature con una firma HMAC-SHA256. Verifica esto para asegurar que el payload fue enviado por Whatalo.

Ejemplo de Verificación

Node.js

import crypto from "crypto";

function verifyWebhookSignature(payload, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(payload)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Python

import hmac
import hashlib

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

Política de Reintentos

Si tu endpoint devuelve un código de estado diferente a 2xx, Whatalo reintenta con backoff exponencial:

Intento	Demora
1er reintento	1 minuto
2do reintento	5 minutos
3er reintento	30 minutos
4to reintento	2 horas
5to reintento	12 horas

Después de 5 intentos fallidos, la entrega del webhook se marca como fallida. Puedes reintentar manualmente desde el Developer Dashboard.

On this page