Actualizar un webhook

PATCH/v1/webhooks/{id}

Para desarrolladores

Descripción

Edita el nombre, la URL, los tipos de evento o el estado de un webhook. Es una actualización parcial: un campo omitido conserva su valor.

El secreto de firma no se edita con este endpoint: se reemplaza con POST /v1/webhooks/{id}/rotate-secret.

Autenticación

Authorizationbearer tokenheaderobligatorio

API key con scope webhooks:write. Formato: Bearer <API_KEY>.

X-Instance-Slugstringheaderobligatorio

Identificador de su instancia. Ver Autenticación.

Request

Path params:

idintegerobligatorio

Identificador del webhook.

Body:

{
  "events": null,
  "is_active": false
}

namestring

1–255 caracteres. No acepta null.

urlstring

Mismos requisitos que al crear. No acepta null.

eventsstring[], enum: `mail.sent | mail.bounced | mail.dropped | mail.opened | mail.clicked | mail.unsubscribed | mail.resubscribed | mail.complained` | null

Reemplaza la lista completa. null recibe todos los tipos.

is_activeboolean

false pausa el webhook, true lo reanuda (ver Notas). No acepta null.

Response

200 OKDevuelve un objeto con los campos que siguen.

idintegersiempre presente

Identificador del webhook.

namestringsiempre presente

—

urlstringsiempre presente

Endpoint que recibe las entregas.

eventsstring[] | nullsiempre presente

Tipos de evento que recibe. null recibe todos. Ver Eventos.

is_activebooleansiempre presente

false si el webhook está pausado.

last_success_atstring (date-time) | nullsiempre presente

Última entrega respondida con 2xx.

last_failure_atstring (date-time) | nullsiempre presente

Última entrega fallida.

last_status_codeinteger | nullsiempre presente

Código HTTP de la última entrega. null si no hubo respuesta, por timeout o error de conexión.

consecutive_failuresintegersiempre presente

Entregas fallidas seguidas desde el último éxito.

failing_sincestring|nullsiempre presente

Momento del primer fallo de la racha en curso, o null si la última entrega fue exitosa.

auto_paused_atstring (date-time) | nullsiempre presente

Momento en que el webhook se pausó por fallos persistentes. null si no está pausado automáticamente. Ver Pausa automática.

previous_secret_expires_atstring (date-time) | nullsiempre presente

Hasta cuándo el secreto anterior a la última rotación firma junto al vigente. null si no hay un secreto anterior vigente. Ver Rotar el secreto.

created_atstring (date-time)siempre presente

—

updated_atstring (date-time)siempre presente

Última modificación de la configuración del webhook. Una entrega no la cambia.

Errores

Código	Cuándo
404	El webhook no existe en la instancia (webhook_not_found).
422	El body no es válido (por ejemplo, null en name, url o is_active), o la URL nueva no cumple los requisitos: errors[].code es webhook_url_insecure o webhook_url_not_allowed.

Detalle completo en Errores genéricos: not-found y Errores por campo (422).

Notas

• Mientras un webhook está pausado no recibe entregas: los eventos que ocurren en ese lapso no se entregan después, y un reintento pendiente que vence durante la pausa se descarta. Los que vencen después de reanudarlo se entregan.
• Reanudar un webhook pausado reinicia consecutive_failures y quita auto_paused_at. La entrega siguiente se intenta en el momento. Ver Pausa automática.
• Cambiar la URL también reinicia consecutive_failures, pero un webhook pausado sigue pausado hasta que se reanude.
• Enviar is_active: true a un webhook que ya está activo, o la misma URL que tiene, no reinicia nada.
• Cambiar la URL no cambia el secreto de firma.

Request

curl -X PATCH "https://$API_HOST/v1/webhooks/3" \
-H "Authorization: Bearer $API_KEY" \
-H "X-Instance-Slug: $SLUG" \
-H "Content-Type: application/json" \
-d '{
  "is_active": false
}'

Response

{
"id": 3,
"name": "CRM de ventas",
"url": "https://hooks.example.com/fidelizador",
"events": null,
"is_active": false,
"last_success_at": "2026-09-13T12:00:04Z",
"last_failure_at": null,
"last_status_code": 200,
"consecutive_failures": 0,
"failing_since": null,
"auto_paused_at": null,
"previous_secret_expires_at": null,
"created_at": "2026-09-10T15:30:00Z",
"updated_at": "2026-09-14T10:05:12Z"
}