Crear un webhook

Referencia › Crear un webhook

Webhooks

# Crear un webhook

POST https://api.wizerp.com/api/v1/webhooks

Da de alta una URL de tu sistema para recibir avisos cuando algo cambia en Wizerp, en vez de consultar una y otra vez. Cada aviso es un POST JSON firmado con HMAC-SHA256 (cabecera X-Wizerp-Firma). La guía de verificación y el catálogo de eventos están en https://developer.wizerp.com/webhooks/.

La respuesta trae el secreto de firma (whsec_…) UNA sola vez: guárdalo. Repetir la petición con la misma Idempotency-Key devuelve el webhook con secreto null; si lo perdiste, rótalo con POST /webhooks/{clave}/secreto.

Reglas: https al puerto 443, con nombre de dominio (no IP), que resuelva a una dirección pública; no se siguen redirecciones. Hasta 10 webhooks por empresa y una URL no se repite. Cada evento exige que la llave tenga el permiso de lectura de su recurso (venta.creada pide ventas:read, etc.), y cualquier acción posterior sobre el webhook (editar, borrar, rotar, probar, reenviar) exige los permisos de lectura de TODOS sus eventos. Las entregas NO cuentan contra el cupo mensual de la API.

Toda escritura necesita la cabecera Idempotency-Key: un valor único por operación (por ejemplo un UUID) que repites tal cual al reintentar. Con la misma clave y los mismos datos se devuelve la respuesta guardada, sin duplicar; con la misma clave y datos distintos responde 409.

Permiso: webhooks:write

## Cuerpo JSON
- `url` (texto): URL https de tu sistema que recibirá los avisos (máximo 500). Obligatoria.
- `eventos` (lista): Lista de eventos a recibir (al menos uno): venta.creada, factura.timbrada, factura.cancelada, cxc.pago_aplicado, cliente.creado, cliente.actualizado, producto.creado, producto.actualizado, inventario.existencia_cambiada, oportunidad.creada, oportunidad.etapa_cambiada. Obligatoria.
- `descripcion` (texto): Texto libre para reconocerlo (máximo 120).

POST https://api.wizerp.com/api/v1/webhooks

https://api.wizerp.com/api/v1/webhooks

Da de alta una URL de tu sistema para recibir avisos cuando algo cambia en Wizerp, en vez de consultar una y otra vez. Cada aviso es un POST JSON firmado con HMAC-SHA256 (cabecera X-Wizerp-Firma). La guía de verificación y el catálogo de eventos están en https://developer.wizerp.com/webhooks/.

La respuesta trae el secreto de firma (whsec_…) UNA sola vez: guárdalo. Repetir la petición con la misma Idempotency-Key devuelve el webhook con secreto null; si lo perdiste, rótalo con POST /webhooks/{clave}/secreto.

Reglas: https al puerto 443, con nombre de dominio (no IP), que resuelva a una dirección pública; no se siguen redirecciones. Hasta 10 webhooks por empresa y una URL no se repite. Cada evento exige que la llave tenga el permiso de lectura de su recurso (venta.creada pide ventas:read, etc.), y cualquier acción posterior sobre el webhook (editar, borrar, rotar, probar, reenviar) exige los permisos de lectura de TODOS sus eventos. Las entregas NO cuentan contra el cupo mensual de la API.

Toda escritura necesita la cabecera Idempotency-Key: un valor único por operación (por ejemplo un UUID) que repites tal cual al reintentar. Con la misma clave y los mismos datos se devuelve la respuesta guardada, sin duplicar; con la misma clave y datos distintos responde 409.

Requiere el permiso webhooks:write en la llave · contrato del 2026-10-12

Cuerpo JSON

Además, toda escritura necesita la cabecera Idempotency-Key: un valor único por operación (por ejemplo un UUID) que repites tal cual al reintentar.

url texto obligatorio

URL https de tu sistema que recibirá los avisos (máximo 500). Obligatoria.

eventos lista obligatorio

Lista de eventos a recibir (al menos uno): venta.creada, factura.timbrada, factura.cancelada, cxc.pago_aplicado, cliente.creado, cliente.actualizado, producto.creado, producto.actualizado, inventario.existencia_cambiada, oportunidad.creada, oportunidad.etapa_cambiada. Obligatoria.

descripcion texto

Texto libre para reconocerlo (máximo 120).

Respuestas

400 Petición mal formada: filtro no permitido, filtro vacío, cursor o límite inválidos, o una cabecera de navegador

401 La llave no es válida, está revocada o venció (llave_invalida), o el usuario dueño de la llave ya no tiene acceso a la empresa (llave_sin_titular)

402 Tu empresa no tiene un plan Pro vigente (plan_requerido). Mientras los límites estén en modo de aviso, esta situación sigue contestando 401 llave_invalida

403 La llave no tiene el permiso que pide esta operación (sin_permiso), o no tiene aceptados los términos de uso de la API vigentes (terminos_pendientes: acéptalos en Wizerp, Configuración › Llaves de API)

404 La ruta no existe, o tu empresa no tiene la API habilitada

409 Conflicto: misma Idempotency-Key con datos distintos, o ya existe un registro con ese identificador (RFC, SKU)

413 El cuerpo pasa del máximo

415 El cuerpo no va como JSON (falta Content-Type: application/json)

422 Un dato no es válido para tu empresa

429 Pasaste el ritmo de 150 peticiones por minuto de tu llave (limite_excedido) o el cupo mensual de tu empresa (cupo_agotado). La respuesta trae Retry-After

500 Falló de nuestro lado. Reintenta y reporta el valor de peticion

503 Tu empresa tiene demasiadas peticiones en curso, o la búsqueda no está disponible. Trae Retry-After

Lenguaje

Petición · cURL

curl -X POST https://api.wizerp.com/api/v1/webhooks \
  -H "Authorization: Bearer wzk_live_…" \
  -H "X-Wizerp-Key-Id: 208_a3f91c7d" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -d '{"url":"ejemplo","eventos":"ejemplo","descripcion":"ejemplo"}'

$ch = curl_init('https://api.wizerp.com/api/v1/webhooks');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer wzk_live_…',
    'X-Wizerp-Key-Id: 208_a3f91c7d',
    'Content-Type: application/json',
    'Idempotency-Key: 3fa85f64-5717-4562-b3fc-2c963f66afa6',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS,
    '{"url":"ejemplo","eventos":"ejemplo","descripcion":"ejemplo"}');
$r = json_decode(curl_exec($ch), true);

const r = await fetch(
  "https://api.wizerp.com/api/v1/webhooks",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer wzk_live_…",
      "X-Wizerp-Key-Id": "208_a3f91c7d",
      "Content-Type": "application/json",
      "Idempotency-Key": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    },
    body: JSON.stringify({"url":"ejemplo","eventos":"ejemplo","descripcion":"ejemplo"}),
  }
);
const datos = await r.json();

import requests

r = requests.post(
    "https://api.wizerp.com/api/v1/webhooks",
    headers={
        "Authorization": "Bearer wzk_live_…",
        "X-Wizerp-Key-Id": "208_a3f91c7d",
        "Idempotency-Key": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    },
    json={"url":"ejemplo","eventos":"ejemplo","descripcion":"ejemplo"},
)
datos = r.json()

Las escrituras se prueban desde tu propio sistema con tu llave; la consola pública es solo para consultas. Copia el ejemplo de arriba: ya lleva el cuerpo y la cabecera Idempotency-Key.

Respuesta elige un ejemplo

{
    "ok": true,
    "webhook": {
        "clave": 184027
    },
    "secreto": "texto",
    "nota": "texto"
}

{
    "ok": false,
    "error": {
        "codigo": "json_invalido",
        "mensaje": "Petición mal formada: filtro no permitido, filtro vacío, cursor o límite inválidos, o una cabecera de navegador",
        "peticion": "req_dca2d22e3324f9a8"
    }
}

{
    "ok": false,
    "error": {
        "codigo": "llave_invalida",
        "mensaje": "La llave no es válida, está revocada o venció (llave_invalida), o el usuario dueño de la llave ya no tiene acceso a la empresa (llave_sin_titular)",
        "peticion": "req_dca2d22e3324f9a8"
    }
}

{
    "ok": false,
    "error": {
        "codigo": "limite_excedido",
        "mensaje": "Pasaste el ritmo de 150 peticiones por minuto de tu llave (limite_excedido) o el cupo mensual de tu empresa (cupo_agotado). La respuesta trae Retry-After",
        "peticion": "req_dca2d22e3324f9a8"
    }
}

Ver la referencia completa