Eventos y webhooks¶

Tus propios programas pueden seguir lo que cambia en OS sin pedir una y otra vez todas las listas. Cada cambio en las personas, los ajustes o el servicio de tu organización se registra como un evento. Tu programa lee esos eventos del feed, o los recibe como un webhook firmado en una dirección que has registrado.

Un evento no es un aviso. Un aviso es una noticia para personas, en su idioma. Un evento es una referencia a algo que cambió, pensada para un programa.

Qué contiene un evento¶

{"id": "evt_01JA...",
 "type": "directory.membership.deactivated",
 "organisation_id": "org_7Hq2...",
 "cursor": "1187",
 "created_at": "2026-10-17T09:14:03Z",
 "refs": {"membership_id": "mem_01J9...", "principal_kind": "person", "status": "deactivated"}}

Referencias, no contenido. refs contiene ids, estados y los nombres de los campos modificados. Nunca un nombre, un correo electrónico, un importe ni nada que alguien escribió. Si tu programa quiere saber más, pide la cosa misma a OS, y OS decide entonces de nuevo qué puede ver.
El cursor es un número en forma de texto, numerado de forma continua por organización, en el orden en que OS registró los eventos.
Orden. Dos cambios muy seguidos pueden registrarse en cualquiera de los dos órdenes, y los webhooks pueden llegar en cualquier orden. Ordena por cursor, y vuelve a leer la cosa cuando importe su estado actual.

Qué tipos de eventos existen está en Eventos.

El feed o un webhook¶

	El feed	Un webhook
Cómo	tu programa pide `GET .../events?cursor=`	OS envía cada evento a tu dirección
Cuándo	cuando tu programa quiere, por ejemplo cada minuto	en pocos segundos
Qué guardas	el último cursor que procesaste	nada: OS reintenta hasta que funciona
Perdido	lee desde tu último cursor	lee el feed desde tu último cursor

OS conserva los eventos siete días. Si pides el feed con un cursor cuyos eventos siguientes ya no están, OS responde 410: vuelve a leer el estado y empieza sin cursor.

Quién ve qué¶

Un webhook actúa en nombre de una cuenta de tu organización, normalmente una cuenta de servicio, y nunca en nombre de quien lo registró. En cada entrega OS decide de nuevo si esa cuenta puede ver el evento: necesita see sobre event, y see sobre la cosa de la que trata el evento. Si la cuenta no ve a un miembro, el webhook tampoco recibe los eventos sobre ese miembro. Una entrega así aparece en el registro como omitida, para que puedas ver por qué no llegó.

Quien lee el feed ve del mismo modo solo los eventos que puede ver.

Registrar un webhook solo puede quien tiene write sobre webhook, puede modificar la cuenta y tiene él mismo todo lo que tiene esa cuenta. Un administrador (org-admin) lo tiene.

Cuando una dirección no responde¶

OS reintenta una entrega fallida tras aproximadamente 1 minuto, 5 minutos, 30 minutos, 2 horas, 6 horas, 12 horas y 24 horas: ocho intentos en casi dos días. Si falla cinco veces seguidas, el webhook pasa a estar fallando: OS envía entonces una entrega a la vez y retiene el resto. Cuando una funciona, el webhook vuelve a estar activo y sigue el resto. Si lleva tres días fallando, o la cuenta ya no está activa, se desactiva. Los administradores de tu organización reciben un aviso en ambos casos. Los eventos permanecen en el feed, y un administrador puede volver a activar el webhook.

Una dirección que responde 410 dice que ya no existe: OS desactiva el webhook de inmediato.

Seguridad¶

Cada entrega está firmada con el secreto del webhook. Comprueba la firma antes de hacer nada con el contenido (cómo).
OS solo envía a direcciones https con un nombre de host que se alcanza desde internet. Una dirección que lleva a una dirección interna o privada, OS la rechaza, al registrar y en cada intento.
OS no sigue ninguna redirección y no lee la respuesta de tu dirección.
No pongas ningún secreto en la dirección: quien puede ver el webhook ve la dirección.

Los webhooks solo están activados cuando Artific los ha activado para tu entorno. Hasta entonces, OS responde 409 al registrar; el feed funciona.