PATCH /v1/webhooks/{id}

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 por acá: se reemplaza con POST /v1/webhooks/{id}/rotate-secret.

Autenticación

Authorizationbearer tokenheaderobligatorio

API key con scope webhooks:write. Formato: Bearer FD.<key_id>.<token>.

X-Instance-Slugstringheaderobligatorio

Request

Path params:

idinteger

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. Reanudar un webhook pausado reinicia su conteo de fallos y quita la pausa automática. No acepta null.

Response

200 OKEl webhook actualizado, con los mismos campos que `GET /v1/webhooks/{id}`.

idintegerobligatorio

Identificador del webhook.

namestringobligatorio

—

urlstringobligatorio

Endpoint que recibe las entregas.

eventsstring[] | nullobligatorio

Tipos de evento que recibe. null recibe todos. Ver Eventos *(pendiente de publicación)*.

is_activebooleanobligatorio

false si el webhook está pausado.

last_success_atstring (date-time) | nullobligatorio

Última entrega respondida con 2xx.

last_failure_atstring (date-time) | nullobligatorio

Última entrega fallida.

last_status_codeinteger | nullobligatorio

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

consecutive_failuresintegerobligatorio

Entregas fallidas seguidas desde el último éxito.

auto_paused_atstring (date-time) | nullobligatorio

Momento en que el webhook se pausó por fallos persistentes. null si no está pausado automáticamente. Ver Pausa automática *(pendiente de publicación)*.

previous_secret_expires_atstring (date-time) | nullobligatorio

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 *(pendiente de publicación)*.

created_atstring (date-time)obligatorio

—

updated_atstring (date-time)obligatorio

Ú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 y Errores genéricos.

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. Cambiar la URL también reinicia consecutive_failures, pero un webhook pausado sigue pausado hasta reanudarlo. Enviar is_active: true a un webhook que ya está activo, o la misma URL que tiene, no reinicia nada. Ver Pausa automática (pendiente de publicación).
• 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,
"auto_paused_at": null,
"previous_secret_expires_at": null,
"created_at": "2026-09-10T15:30:00Z",
"updated_at": "2026-09-14T10:05:12Z"
}