Descripción general de los webhooks

Sursa registra un evento por cada cambio importante: una tarjeta se publica, se verifica o se archiva, un aviso se lee, una pregunta se queda sin respuesta. Puede recibir los eventos de dos maneras y usar las dos a la vez:

	Webhooks	Feed de eventos
Cómo	Sursa envía cada evento a su dirección HTTPS en el momento en que ocurre.	Usted lee `GET /v1/webhook-events` cuando quiere.
Latencia	Segundos.	Tan a menudo como consulte el feed.
Requisitos	Un receptor HTTPS público.	Solo una clave de API con el rol `admin` y el ámbito `webhooks:manage`.
Útil para	Reaccionar a los cambios: avisar, sincronizar, iniciar un flujo de trabajo.	Trabajos por lotes, ponerse al día después de una interrupción del servicio, conciliación.

Los dos llevan los mismos eventos con los mismos ID. Cada evento se conserva en el feed durante 30 días, tanto si algún webhook estaba suscrito a él como si no.

El evento

{
  "id": "evt_0123456789abcdef0123456789abcdef",
  "type": "card.updated",
  "created_at": "2026-10-24T10:00:03Z",
  "org_id": 1,
  "api_version": "1.60.0",
  "sequence": 1042,
  "object": {"type": "card", "id": "3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60"},
  "payload": "full",
  "data": {
    "card": {"id": "3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60", "title": "Refund policy", "collection": "support", "version": 4},
    "actor_id": 7,
    "previous_attributes": {"title": "Refunds"}
  },
  "test": false
}

Campo	Significado
`id`	El ID del evento: `evt_` y 32 caracteres hexadecimales. Es el mismo en cada intento de entrega y en el feed.
`type`	Qué ocurrió, con la forma `<object>.<past-tense verb>`: `card.updated`, `access_request.resolved`.
`created_at`	Cuándo ocurrió el cambio, en UTC.
`api_version`	La versión de la API cuyo esquema sigue `data`.
`object`	El tipo y el ID del objeto al que se refiere el evento.
`data`	Los detalles. Su forma depende del tipo y se describe en el catálogo de eventos.
`data.previous_attributes`	En los eventos `*.updated`: los valores anteriores de los campos que cambiaron.
`sequence`, `payload`, `test`	Solo en las entregas de webhooks: la posición en el orden del webhook, el modo de carga útil y si se trata de un evento de prueba.

data contiene solo lo que cualquier lector del objeto podría ver mediante la API. Nunca contiene listas de acceso, los permisos de otras personas ni campos ocultos. Los motivos de los eventos son códigos neutros breves, como no_hits, restricted o index_failed.

Tipos de evento

Los eventos abarcan estas áreas:

Área	Ejemplos
Tarjetas	`card.created`, `card.updated`, `card.published`, `card.archived`, `card.deleted`, `card.indexed`, `card.index_failed`
Verificación	`card.verified`, `card.unverified`, `verification.expired`, `verification.requested`
Estructura	`collection.created`, `folder.updated`
Colaboración	`comment.created`, `draft.publish_requested`, `announcement.sent`, `announcement.read`
Respuestas	`question.unanswered`, `question.feedback_created`, `access_request.created`
Personas y acceso	`user.created`, `user.deactivated`, `group.member_added`, `api_key.expiring`
Fuentes e importación	`source.sync_completed`, `import.sync_completed`, `import.document_failed`
Trabajos	`job.completed`, `job.failed`, `export.ready`
Webhooks	`webhook.endpoint_disabled`, `webhook.ping`

La lista completa, con el esquema y un ejemplo de cada evento, está en el catálogo de eventos de la referencia de la API. GET /v1/webhooks/catalog devuelve los tipos disponibles en su instalación.

Con el tiempo se añaden tipos de evento nuevos, y los eventos existentes ganan campos. Los tipos de evento nunca cambian de nombre ni se eliminan. Su receptor debe omitir los tipos y los campos que no conozca.

Quién recibe qué

Un webhook recibe un evento solo si el objeto del evento es visible para el webhook, de la misma manera que para una clave de API: según su rol, su perfil de datos y sus colecciones. Un webhook limitado a la colección support nunca recibe eventos sobre tarjetas de finance. Los eventos sobre personas, claves, fuentes, importaciones, trabajos, exportaciones, facturación, aplicaciones y los propios webhooks solo se envían a los webhooks con el rol admin.

Dentro de eso, cada webhook elige sus eventos:

por tipo, con máscaras: card.* para todos los eventos de tarjetas, * para todos los eventos;
por colección y por etiqueta, en los eventos de tarjetas.

El modo de carga útil de un webhook es full (el evento con data, el predeterminado) o thin (el evento sin data: su receptor lee el objeto mediante la API con su propia clave y siempre ve su estado actual).

La entrega en resumen

Un POST HTTPS con el evento como JSON, firmado con el secreto del webhook en dos formatos: Standard Webhooks (webhook-signature) y el anterior X-KB-Signature.
Cualquier respuesta 2xx en menos de 10 segundos es un éxito.
Un fallo se reintenta durante casi tres días con pausas cada vez más largas. Se respeta Retry-After en una respuesta 429 o 503; 410 desactiva el webhook; 10 fallos seguidos lo ponen en pausa hasta que se reanuda.
Las entregas a un mismo webhook se envían estrictamente en orden. Un webhook lento no retrasa a los demás.
El mismo evento puede llegar más de una vez: descarte los duplicados por webhook-id.

Recibir webhooks recorre un receptor completo, con comprobación de firmas en Node.js, Python y Go.

Gestionar los webhooks

Tarea	Endpoint
Crear un webhook y obtener su secreto	`POST /v1/webhooks`
Cambiar la dirección, los eventos o el estado	`PATCH /v1/webhooks/{webhook_id}`
Enviar un evento de prueba	`POST /v1/webhooks/{webhook_id}/test`
Rotar el secreto	`POST /v1/webhooks/{webhook_id}/rotate-secret`
Reanudar un webhook en pausa	`POST /v1/webhooks/{webhook_id}/resume`
Ver las entregas y las respuestas	`GET /v1/webhooks/{webhook_id}/deliveries`
Volver a enviar una entrega	`POST /v1/webhooks/{webhook_id}/deliveries/{delivery_id}/redeliver`

Para gestionar los webhooks hace falta una clave con el rol admin y el ámbito webhooks:manage, o un administrador en la interfaz de administración. Una organización puede tener hasta 20 webhooks. Los webhooks forman parte del plan de la organización; si el plan no los incluye, estos endpoints responden 403 con el código webhooks.feature_disabled.