PATCH/v1/webhooks/{webhook_id}

Actualizar un webhook

update_webhook

Cambia la URL, la descripción, las suscripciones, el acceso, los filtros, los encabezados personalizados, la autorización saliente y el estado de activación. active: true activa el webhook y levanta la pausa, de modo que las entregas acumuladas salen en orden. active: false desactiva el webhook y cancela las entregas pendientes. headers reemplaza toda la lista de encabezados personalizados; un elemento sin value conserva el valor anterior del encabezado con el mismo nombre. auth: null y data_profile_id: null eliminan la autorización saliente y el perfil de datos.

Autenticación

Envíe una clave de API en el encabezado Authorization: Authorization: Bearer <clave>.

Parámetros de ruta

webhook_idintegerobligatorio

Parámetros de encabezado

Idempotency-Keystring
Clave para reintentar de forma segura una escritura: de 1 a 255 caracteres ASCII imprimibles; se recomienda un UUID v4 por operación lógica. Un reintento con la misma clave en un plazo de 24 horas no vuelve a ejecutar la operación: devuelve la respuesta guardada (estado, encabezados y cuerpo) con el encabezado Idempotency-Replayed: true. La misma clave con otro método, otra ruta, otro Content-Type u otro cuerpo devuelve 409 api.idempotency_mismatch; mientras la primera solicitud sigue en curso, 409 api.idempotency_in_progress con Retry-After: 1. Tras una respuesta 5xx o 429, la clave se libera y un reintento vuelve a ejecutar la operación. La clave se aplica a la organización y a quien llama a la API (clave de API, usuario o clave de fuente personalizada).
length ≥ 1, length ≤ 255

Cuerpo de la solicitud

application/json

Objeto: WebhookUpdate

urlstring | null
length ≤ 2048
descriptionstring | null
length ≤ 200
eventsarray of WebhookEventFilter | null
items ≥ 1
activeboolean | null
rolestring | null
Valores permitidos: admineditorviewernull
data_profile_idinteger | null
null elimina el perfil de datos.
collection_idsarray of integer | null
Colecciones del webhook. Una lista vacía significa todas las colecciones disponibles para el rol y el perfil de datos; sin valor o con null, no cambian. Una clave que está limitada a colecciones solo ve y cambia los webhooks cuyas colecciones están en su lista (los demás webhooks devuelven 404 webhooks.not_found). Una lista vacía o una colección fuera de su lista devuelven 403 webhooks.collections_outside_key.
items ≤ 200
tagsarray of string | null
items ≤ 50
payloadstring | null
Valores permitidos: fullthinnull
headersarray of WebhookHeaderInput | null
items ≤ 10
authWebhookAuthInput | null
null elimina la autorización saliente.

Respuestas

200Respuesta correcta

Encabezados de la respuesta

RateLimit-Policy
Límites vigentes, en el formato del borrador del IETF draft-ietf-httpapi-ratelimit-headers: elementos separados por comas "<name>";q=<quota>;w=<window in seconds>. key es la frecuencia de solicitudes de la clave de API (la cuota es la ráfaga y la ventana es el tiempo que tarda en recargarse por completo; para una sesión es user y sin credenciales, ip); minute, day y month son las cuotas de la organización para el minuto, el día y el mes naturales en UTC.
RateLimit
Lo que queda de cada límite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Límite de la entrada más estricta de RateLimit-Policy (la que tiene menos solicitudes restantes).
X-RateLimit-Remaining
Solicitudes restantes del límite más estricto.
X-RateLimit-Reset
Segundos hasta que se restablece el límite más estricto.
Idempotency-Replayed
true significa que la respuesta se reprodujo a partir de la guardada para esta Idempotency-Key: la operación no se volvió a ejecutar.

application/json

Objeto: WebhookEndpoint

idintegerobligatorio
urlstringobligatorio
descriptionstringobligatorio
eventsarray of WebhookEventFilterobligatorio
activebooleanobligatorio
statusWebhookStatusobligatorio
paused_atstring (date-time) | null
paused_reasonstring | null
failures: 10 intentos fallidos seguidos; feature_disabled: el plan no incluye webhooks.
disabled_reasonstring | null
gone: el receptor respondió 410; manual: lo desactivó un administrador.
Valores permitidos: gonemanualnull
disabled_atstring (date-time) | null
roleWebhookRoleobligatorio
data_profile_idinteger | null
Perfil de datos del webhook (null significa sin perfil, como en una clave de API con el mismo rol).
collection_idsarray of integerobligatorio
Colecciones sobre las que el webhook recibe eventos; vacío significa todas las colecciones disponibles para el rol y el perfil de datos.
tagsarray of stringobligatorio
Eventos de tarjetas solo para las tarjetas con alguna de estas etiquetas; vacío significa sin filtro.
payloadWebhookPayloadModeobligatorio
headersarray of WebhookHeaderobligatorio
auth_typestring | null
Tipo de la autorización saliente (null significa ninguna).
Valores permitidos: bearerbasicnull
auth_setbooleanobligatorio
Indica si la autorización saliente está configurada (los valores nunca se devuelven).
previous_secret_valid_untilstring (date-time) | null
Hasta cuándo las entregas se firman también con el secreto anterior (null significa que no hay solapamiento).
healthWebhookHealth
consecutive_failuresintegerobligatorio
last_delivery_atstring (date-time) | null
last_success_atstring (date-time) | null
last_errorstring | null
created_byinteger | null
created_by_namestring | null
created_atstring (date-time)obligatorio
updated_atstring (date-time)obligatorio

400La solicitud no es válida: el valor de un parámetro o el estado del objeto no permiten la acción (`detail` es un mensaje).

Encabezados de la respuesta

RateLimit-Policy
Límites vigentes, en el formato del borrador del IETF draft-ietf-httpapi-ratelimit-headers: elementos separados por comas "<name>";q=<quota>;w=<window in seconds>. key es la frecuencia de solicitudes de la clave de API (la cuota es la ráfaga y la ventana es el tiempo que tarda en recargarse por completo; para una sesión es user y sin credenciales, ip); minute, day y month son las cuotas de la organización para el minuto, el día y el mes naturales en UTC.
RateLimit
Lo que queda de cada límite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Límite de la entrada más estricta de RateLimit-Policy (la que tiene menos solicitudes restantes).
X-RateLimit-Remaining
Solicitudes restantes del límite más estricto.
X-RateLimit-Reset
Segundos hasta que se restablece el límite más estricto.

application/json

Objeto: Error

401No se enviaron credenciales (ni una cookie de sesión ni una clave de API) o no se encontró la clave.

Encabezados de la respuesta

RateLimit-Policy
Límites vigentes, en el formato del borrador del IETF draft-ietf-httpapi-ratelimit-headers: elementos separados por comas "<name>";q=<quota>;w=<window in seconds>. key es la frecuencia de solicitudes de la clave de API (la cuota es la ráfaga y la ventana es el tiempo que tarda en recargarse por completo; para una sesión es user y sin credenciales, ip); minute, day y month son las cuotas de la organización para el minuto, el día y el mes naturales en UTC.
RateLimit
Lo que queda de cada límite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Límite de la entrada más estricta de RateLimit-Policy (la que tiene menos solicitudes restantes).
X-RateLimit-Remaining
Solicitudes restantes del límite más estricto.
X-RateLimit-Reset
Segundos hasta que se restablece el límite más estricto.

application/json

Objeto: Error

403La acción no está permitida: el rol no es suficiente, no hay acceso a la colección o a la tarjeta, la solicitud se ejecuta en modo «View as», o la organización está suspendida o eliminada (`detail` es un objeto con `code: org_suspended | org_deleted`).

Encabezados de la respuesta

RateLimit-Policy
Límites vigentes, en el formato del borrador del IETF draft-ietf-httpapi-ratelimit-headers: elementos separados por comas "<name>";q=<quota>;w=<window in seconds>. key es la frecuencia de solicitudes de la clave de API (la cuota es la ráfaga y la ventana es el tiempo que tarda en recargarse por completo; para una sesión es user y sin credenciales, ip); minute, day y month son las cuotas de la organización para el minuto, el día y el mes naturales en UTC.
RateLimit
Lo que queda de cada límite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Límite de la entrada más estricta de RateLimit-Policy (la que tiene menos solicitudes restantes).
X-RateLimit-Remaining
Solicitudes restantes del límite más estricto.
X-RateLimit-Reset
Segundos hasta que se restablece el límite más estricto.

application/json

Objeto: Error

404El objeto no existe o no está disponible para usted. La API no confirma la existencia de un objeto restringido.

Encabezados de la respuesta

RateLimit-Policy
Límites vigentes, en el formato del borrador del IETF draft-ietf-httpapi-ratelimit-headers: elementos separados por comas "<name>";q=<quota>;w=<window in seconds>. key es la frecuencia de solicitudes de la clave de API (la cuota es la ráfaga y la ventana es el tiempo que tarda en recargarse por completo; para una sesión es user y sin credenciales, ip); minute, day y month son las cuotas de la organización para el minuto, el día y el mes naturales en UTC.
RateLimit
Lo que queda de cada límite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Límite de la entrada más estricta de RateLimit-Policy (la que tiene menos solicitudes restantes).
X-RateLimit-Remaining
Solicitudes restantes del límite más estricto.
X-RateLimit-Reset
Segundos hasta que se restablece el límite más estricto.

application/json

Objeto: Error

422Error de validación: el cuerpo o los parámetros no coinciden con el esquema (`detail` es una lista de errores de validación), o el valor de un parámetro está fuera del rango permitido (`detail` es un mensaje).

Encabezados de la respuesta

RateLimit-Policy
Límites vigentes, en el formato del borrador del IETF draft-ietf-httpapi-ratelimit-headers: elementos separados por comas "<name>";q=<quota>;w=<window in seconds>. key es la frecuencia de solicitudes de la clave de API (la cuota es la ráfaga y la ventana es el tiempo que tarda en recargarse por completo; para una sesión es user y sin credenciales, ip); minute, day y month son las cuotas de la organización para el minuto, el día y el mes naturales en UTC.
RateLimit
Lo que queda de cada límite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Límite de la entrada más estricta de RateLimit-Policy (la que tiene menos solicitudes restantes).
X-RateLimit-Remaining
Solicitudes restantes del límite más estricto.
X-RateLimit-Reset
Segundos hasta que se restablece el límite más estricto.

application/json

Objeto: Error

429Demasiadas solicitudes (`api.rate_limited`), se agotó la cuota de la organización para el minuto, el día o el mes (`api.quota_exceeded`; `error.details` contiene `quota`, `limit` y `reset_at`), se alcanzó el límite de la organización o el servicio de respuestas está ocupado (`answers.engine_busy`). Espere el tiempo indicado en el encabezado `Retry-After`.

Encabezados de la respuesta

Retry-After
Número de segundos que hay que esperar antes de reintentar la solicitud.
RateLimit-Policy
Límites vigentes, en el formato del borrador del IETF draft-ietf-httpapi-ratelimit-headers: elementos separados por comas "<name>";q=<quota>;w=<window in seconds>. key es la frecuencia de solicitudes de la clave de API (la cuota es la ráfaga y la ventana es el tiempo que tarda en recargarse por completo; para una sesión es user y sin credenciales, ip); minute, day y month son las cuotas de la organización para el minuto, el día y el mes naturales en UTC.
RateLimit
Lo que queda de cada límite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Límite de la entrada más estricta de RateLimit-Policy (la que tiene menos solicitudes restantes).
X-RateLimit-Remaining
Solicitudes restantes del límite más estricto.
X-RateLimit-Reset
Segundos hasta que se restablece el límite más estricto.

application/json

Objeto: Error

Códigos de error

Códigos que este endpoint puede devolver en error.code, además de los códigos generales de cualquier solicitud.

Reintentos seguros

Envíe un encabezado Idempotency-Key (por ejemplo, un UUID) con cada POST y PATCH. Un reintento con la misma clave en un plazo de 24 horas devuelve la respuesta guardada en lugar de volver a ejecutar la solicitud.

Límites de frecuencia

Las respuestas incluyen los encabezados RateLimit y RateLimit-Policy y los anteriores X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset. Una respuesta 429 lleva Retry-After en segundos: espere y vuelva a intentarlo.

← webhooks · Referencia de la API

curl -X PATCH 'https://api.sursa.com/v1/webhooks/1' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/webhooks/sursa","description":"Customer support articles","events":["card.*"]}' \
  -H "Authorization: Bearer $SURSA_API_KEY"

Probar

Clave de API

La clave se queda en la memoria de esta pestaña y solo se envía a https://api.sursa.com.

Las solicitudes actúan sobre los datos reales de su organización.

Idempotency-Key header

webhook_id path *

Idempotency-Key

Si este campo está vacío, se genera una clave nueva para cada solicitud.

Cuerpo de la solicitud (JSON)