Editar, pausar o reactivar un webhook

Referencia › Editar, pausar o reactivar un webhook

Webhooks

Editar, pausar o reactivar un webhook

# Editar, pausar o reactivar un webhook

PUT https://api.wizerp.com/api/v1/webhooks/{clave}

Cambia la URL, los eventos o la descripción, y pausa (activo false) o reactiva (activo true) el webhook. Sólo se cambian los campos que mandas.

Mientras está pausado no se generan avisos para él y los pendientes se descartan. Un webhook desactivado automáticamente (estado desactivado, tras más de un día de entregas fallidas) se reactiva con activo true, que además reinicia su racha de fallos.

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): Nueva URL https (mismas reglas que al crear).
- `eventos` (lista): Nueva lista COMPLETA de eventos (reemplaza la anterior): 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.
- `descripcion` (texto): Nueva descripción; null la quita.
- `activo` (booleano): false pausa el webhook; true lo reactiva (también si se desactivó por fallos).

PUT https://api.wizerp.com/api/v1/webhooks/{clave}

https://api.wizerp.com/api/v1/webhooks/{clave}

Cambia la URL, los eventos o la descripción, y pausa (activo false) o reactiva (activo true) el webhook. Sólo se cambian los campos que mandas.

Mientras está pausado no se generan avisos para él y los pendientes se descartan. Un webhook desactivado automáticamente (estado desactivado, tras más de un día de entregas fallidas) se reactiva con activo true, que además reinicia su racha de fallos.

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

Parámetros de ruta

clave entero en la URL

Clave del webhook (la de GET /webhooks).

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

Nueva URL https (mismas reglas que al crear).

eventos lista

Nueva lista COMPLETA de eventos (reemplaza la anterior): 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.

descripcion texto

Nueva descripción; null la quita.

activo booleano

false pausa el webhook; true lo reactiva (también si se desactivó por fallos).

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 PUT https://api.wizerp.com/api/v1/webhooks/{clave} \
  -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/{clave}');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');
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/{clave}",
  {
    method: "PUT",
    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.put(
    "https://api.wizerp.com/api/v1/webhooks/{clave}",
    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
    }
}

{
    "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