Endpoints de la API. Especificación exacta de cada operación de la API v1 (parámetros, cuerpo, respuestas y ejemplos), generada del documento OpenAPI con el que se valida cada respuesta real. Los procedimientos completos están en Guías.

POST /webhooks

Crear una suscripción

Registra una URL para recibir los eventos indicados. La respuesta trae el secreto de firma (secret) una sola vez: debe guardarse para verificar X-Chainlink-Signature. Si no se envía secret, Chainlink genera uno.

La URL debe usar https:// y apuntar a una dirección pública de internet: se rechazan con 422 las direcciones privadas, locales, de enlace local, CGNAT, multicast, reservadas y de metadatos de la nube, en IPv4 e IPv6, también cuando el dominio resuelve a una de ellas. La comprobación se repite en cada entrega.

Alcance (cliente de integración)
webhooks:manage
Permiso (token de usuario)
users.manage
Idempotency-Key
Opcional
Requisitos
Plan Professional o Enterprise

Cabeceras

  • Idempotency-Key string

    Llave única por operación (se recomienda un UUID v4). Reenviar la misma solicitud con la misma llave en las siguientes 24 horas devuelve la respuesta original sin repetir la operación.

Cuerpo de la solicitud application/json

  • url string (uri) obligatorio

    URL pública con https:// que recibirá los eventos. Se rechazan direcciones privadas, locales, de enlace local, CGNAT, multicast y de metadatos de la nube (IPv4 e IPv6), también si el dominio resuelve a ellas.

  • events array de textos obligatorio
    Valores: receipt.created, receipt.completed, picking.created, picking.completed, transfer.created, transfer.completed, transfer.dispatched, transfer.received, shipment.dispatched, return.received, return.dispositioned, packing_order.transitioned, rfid_validation.completed, product.created, product.updated, stock.updated, layout.published, wave.planned, wave.released, wave.completed, wave.cancelled
  • secret string | null

    Secreto de firma propio; si no se envía, se genera uno.

Respuestas

201 Suscripción creada, con su secreto. Location apunta al nuevo recurso.
  • data objeto obligatorio
    9 campos de data
    • id integer obligatorio
    • url string (uri) obligatorio
    • events array de textos obligatorio
      Valores: receipt.created, receipt.completed, picking.created, picking.completed, transfer.created, transfer.completed, transfer.dispatched, transfer.received, shipment.dispatched, return.received, return.dispositioned, packing_order.transitioned, rfid_validation.completed, product.created, product.updated, stock.updated, layout.published, wave.planned, wave.released, wave.completed, wave.cancelled
    • is_active boolean obligatorio

      Se desactiva sola tras 10 entregas fallidas seguidas.

    • failure_count integer obligatorio
    • last_triggered_at string (date-time) | null
    • created_at string (date-time) | null
    • updated_at string (date-time) | null
    • secret string obligatorio

      Secreto de firma. Solo aparece en esta respuesta.

401 Falta el token o no es válido.

Cuerpo: el sobre de error.

402 La función no está en el plan de la empresa, o la cuenta está suspendida o cancelada.

Cuerpo: el sobre de error.

403 Al cliente le falta el alcance (missing_scope), al usuario el permiso (forbidden), o el token de usuario no tiene acceso a la ruta (client_not_allowed: aplicación móvil o usuario con verificación en dos pasos).

Cuerpo: el sobre de error.

409 Otra solicitud con la misma Idempotency-Key sigue en proceso.

Cuerpo: el sobre de error.

422 Datos no válidos (validation_failed), una llave de idempotencia reutilizada con otra solicitud (idempotency_key_reused) o una regla de negocio que bloquea la operación (rule_blocked).

Cuerpo: el sobre de error.

429 Se superó el límite por minuto. Reintente después de los segundos de Retry-After.

Cuerpo: el sobre de error.

Probar

Probar con una instancia

La solicitud sale del navegador hacia la instancia indicada; nada pasa por chainlink.mx. El token se conserva solo en esta pestaña.

Obtener un token con un cliente de integración

Credenciales de Configuración › Clientes API (grant client_credentials). El secreto se usa una vez y no se guarda. Los tokens de usuario se obtienen fuera de la consola; ver Autenticación.

Solicitud
curl -X POST "https://empresa.chainlink.mx/api/v1/webhooks" \
  -H "Authorization: Bearer $CHAINLINK_TOKEN" \
  -H "Accept: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://erp.example.com/chainlink/webhooks",
    "events": [
        "receipt.completed",
        "picking.completed",
        "stock.updated"
    ]
}'
Respuesta
{
    "data": {
        "id": 3,
        "url": "https://erp.example.com/chainlink/webhooks",
        "events": [
            "receipt.completed",
            "picking.completed",
            "stock.updated"
        ],
        "is_active": true,
        "failure_count": 0,
        "last_triggered_at": null,
        "created_at": "2026-10-06T16:40:00.000000Z",
        "updated_at": "2026-10-06T16:40:00.000000Z",
        "secret": "9f2c1d7e0a5b4c3d8e6f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d"
    }
}