Webhooks: referencia de la API, endpoints y ejemplos

OpenAPI YAML OpenAPI JSON problemas YAML Resumen de la API

Este grupo tiene 9 operaciones, generadas a partir de api/openapi.yaml. Filtre por ruta, acción o autenticación. Cada endpoint indica sus entradas; despliéguelo para ver una plantilla de solicitud y los códigos de respuesta. Las plantillas necesitan sus propios valores y un cuerpo válido según el esquema.

Reemplace los marcadores en mayúsculas con sus valores. Para una solicitud JSON, guarde un cuerpo que coincida con el esquema en request.json. Los ejemplos de cookies usan un frasco de cookies local de una sesión autenticada.

Webhooks: entrega de eventos firmados

GET/api/webhooks¶

Listar webhooks

Lista las notificaciones de webhook del proyecto con la estructura de webhook, de la más antigua a la más reciente (máximo 50); GET /api/notifications lista todos los canales. El secreto de firma nunca se devuelve aquí. Requiere la capacidad de proyecto; una credencial solo de informes se rechaza con 403 forbidden, porque la respuesta incluye las URL de los receptores.

Autenticación: projectBearer O dashboardSession
Cuerpo de la solicitud: ninguno
ID de operación: listWebhooks

Parámetros

Nombre	Enviar	¿Requerido?	Descripción
ScreenRig-Project	encabezado	opcional	Obsoleto por una versión. Debe ser consistente con las concesiones de proyectos JWT; añade encabezados Deprecation y Warning. Sin intercambio de token.

Plantilla y respuestas de solicitud

shell · plantilla de solicitud

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/webhooks'

Respuestas

Estado	Significado	Cuerpo y encabezados
200	Los webhooks del proyecto.	WebhookList (application/json)
predeterminado	Respuesta estable RFC 9457 a problemas. Un 421 server_draining lleva Retry-After de 1 segundo, un 500 not_ready o dependency_unavailable lleva 5, y un 500 manifest_degraded lleva 60, a menos que el manejador establezca un valor más específico.	Problema (application/problem+json)

POST/api/webhooks¶

Crear webhook

Crea un webhook que recibe los eventos duraderos propios del proyecto como POSTs HTTPS firmados. La URL debe ser https en un host público de Internet: un literal IP o todas las respuestas DNS actuales del nombre deben ser públicas (privadas, loopback, link-local, CGNAT, IPv6 fuera de 2000::/3, documentación y otros rangos reservados se rechazan con webhook_url_rejected).

El puerto debe ser 443 (el predeterminado) o 8443, de lo contrario webhook_url_rejected. El host se resuelve y verifica nuevamente antes de cada entrega y la conexión se establece exactamente a la dirección verificada, por lo que una respuesta DNS que cambie después no puede redirigir las entregas. event_types lista tipos exactos de eventos (screen.online) o prefijos terminados en .* (screen.*).

Una organización tiene como máximo 50 notificaciones entre todos los canales (webhook_limit_reached). El servidor genera el secreto de firma y lo devuelve solo en esta respuesta y en rotate-secret; guárdelo. Un reintento exacto con la misma Idempotency-Key devuelve esta misma respuesta, secreto incluido, durante veinticuatro horas.

La entrega empieza con el primer evento posterior a notification.created.

Autenticación: projectBearer
Cuerpo de la solicitud: Escritura de webhook
ID de operación: createWebhook

Parámetros

Nombre	Enviar	¿Requerido?	Descripción
ScreenRig-Project	encabezado	opcional	Obsoleto por una versión. Debe ser consistente con las concesiones de proyectos JWT; añade encabezados Deprecation y Warning. Sin intercambio de token.
Idempotency-Key	encabezado	opcional	Omitir para una operación nueva. Proporcione y reutilice una clave para deduplicar reintentos; el CLI gestiona las claves automáticamente.

Campos del cuerpo de la solicitud

Campo	Descripción
url (requerida, cadena)	URL HTTPS en un host público de Internet, puerto 443 (el predeterminado) o 8443. Sin información de usuario ni fragmento. maxLength: 2048 formato: "uri"
event_types (requerido, WebhookEventTypes)	Tipos de evento exactos, como screen.online, o prefijos que terminan en ., como screen. (todos los tipos que empiezan con screen.). notification.test nunca se distribuye mediante una suscripción; solo lo envía POST /api/webhooks/{id}/test.
habilitado (opcional, booleano)	predeterminado: true
descripción (opcional, cadena)	maxLength: 200

Plantilla y respuestas de solicitud

shell · plantilla de solicitud

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/webhooks'

Respuestas

Estado	Significado	Cuerpo y encabezados
201	Creado. El secreto se muestra solo aquí y en rotar-secreto.	Webhook con secreto (application/json); encabezados: Cache-Control
400	invalid_request o webhook_url_rejected.	Problema (application/problem+json)
409	webhook_limit_reached, idempotency_mismatch o resource_conflict cuando el proyecto no pertenece a ninguna organización.	Problema (application/problem+json)
predeterminado	Respuesta estable RFC 9457 a problemas. Un 421 server_draining lleva Retry-After de 1 segundo, un 500 not_ready o dependency_unavailable lleva 5, y un 500 manifest_degraded lleva 60, a menos que el manejador establezca un valor más específico.	Problema (application/problem+json)

GET/api/webhooks/{id}¶

Obtener webhook

Requiere la capacidad del proyecto; una credencial solo para informes es rechazada con 403 forbidden, porque la respuesta incluye URLs de receptor.

Autenticación: projectBearer O dashboardSession
Cuerpo de la solicitud: ninguno
ID de operación: getWebhook

Parámetros

Nombre	Enviar	¿Requerido?	Descripción
ScreenRig-Project	encabezado	opcional	Obsoleto por una versión. Debe ser consistente con las concesiones de proyectos JWT; añade encabezados Deprecation y Warning. Sin intercambio de token.
id	ruta	requerido

Plantilla y respuestas de solicitud

shell · plantilla de solicitud

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/webhooks/RESOURCE_ID'

Respuestas

Estado	Significado	Cuerpo y encabezados
200	Un webhook.	Webhook (application/json); encabezados: ETag
predeterminado	Respuesta estable RFC 9457 a problemas. Un 421 server_draining lleva Retry-After de 1 segundo, un 500 not_ready o dependency_unavailable lleva 5, y un 500 manifest_degraded lleva 60, a menos que el manejador establezca un valor más específico.	Problema (application/problem+json)

PATCH/api/webhooks/{id}¶

Actualizar webhook

Cambia cualquiera de url, event_types, habilitado y descripción (una descripción vacía la borra). Una nueva url se verifica como al crear.

Establecer enabled true en un webhook deshabilitado borra su estado de fallo y comienza la entrega en el evento que registra el cambio; no se reproducen eventos de mientras estuvo deshabilitado, y las entregas pendientes anteriores al deshabilitado fallan con webhook_disabled. Establecer enabled false falla sus entregas pendientes con webhook_disabled.

Agrega notification.updated. If-Match protege la revisión.

Autenticación: projectBearer
Cuerpo de la solicitud: Parche de webhook
ID de operación: updateWebhook

Parámetros

Nombre	Enviar	¿Requerido?	Descripción
ScreenRig-Project	encabezado	opcional	Obsoleto por una versión. Debe ser consistente con las concesiones de proyectos JWT; añade encabezados Deprecation y Warning. Sin intercambio de token.
id	ruta	requerido
If-Match	encabezado	opcional	Revisión positiva opcional de recurso. Omitir para escribir el recurso actual; una revisión obsoleta suministrada es revision_conflict.
Idempotency-Key	encabezado	opcional	Omitir para una operación nueva. Proporcione y reutilice una clave para deduplicar reintentos; el CLI gestiona las claves automáticamente.

Campos del cuerpo de la solicitud

Campo	Descripción
url (opcional, cadena)	maxLength: 2048 formato: "uri"
event_types (opcional, WebhookEventTypes)	Tipos de evento exactos, como screen.online, o prefijos que terminan en ., como screen. (todos los tipos que empiezan con screen.). notification.test nunca se distribuye mediante una suscripción; solo lo envía POST /api/webhooks/{id}/test.
habilitado (opcional, booleano)
descripción (opcional, cadena)	Una cadena vacía borra la descripción. maxLength: 200

Plantilla y respuestas de solicitud

shell · plantilla de solicitud

curl --request PATCH --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/webhooks/RESOURCE_ID'

Respuestas

Estado	Significado	Cuerpo y encabezados
200	Webhook actualizado.	Webhook (application/json); encabezados: ETag
400	invalid_request o webhook_url_rejected.	Problema (application/problem+json)
412	revision_conflict: If-Match está obsoleto; current_revision del error contiene la revisión actual.	Problema (application/problem+json)
predeterminado	Respuesta estable RFC 9457 a problemas. Un 421 server_draining lleva Retry-After de 1 segundo, un 500 not_ready o dependency_unavailable lleva 5, y un 500 manifest_degraded lleva 60, a menos que el manejador establezca un valor más específico.	Problema (application/problem+json)

ELIMINAR/api/webhooks/{id}¶

Eliminar webhook

Elimina el webhook y agrega notification.deleted. Sus entregas pendientes se marcan como fallidas con webhook_deleted; su registro de entregas ya no es accesible y caduca junto con la retención de eventos.

Autenticación: projectBearer O dashboardSession
Cuerpo de la solicitud: ninguno
ID de operación: deleteWebhook

Parámetros

Nombre	Enviar	¿Requerido?	Descripción
ScreenRig-Project	encabezado	opcional	Obsoleto por una versión. Debe ser consistente con las concesiones de proyectos JWT; añade encabezados Deprecation y Warning. Sin intercambio de token.
id	ruta	requerido
If-Match	encabezado	opcional	Revisión positiva opcional de recurso. Omitir para escribir el recurso actual; una revisión obsoleta suministrada es revision_conflict.
Idempotency-Key	encabezado	opcional	Omitir para una operación nueva. Proporcione y reutilice una clave para deduplicar reintentos; el CLI gestiona las claves automáticamente.

Plantilla y respuestas de solicitud

shell · plantilla de solicitud

curl --request DELETE --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/webhooks/RESOURCE_ID'

Respuestas

Estado	Significado	Cuerpo y encabezados
204	Eliminado.	sin cuerpo; encabezados: Cache-Control
412	revision_conflict: If-Match está obsoleto; current_revision del error contiene la revisión actual.	Problema (application/problem+json)
predeterminado	Respuesta estable RFC 9457 a problemas. Un 421 server_draining lleva Retry-After de 1 segundo, un 500 not_ready o dependency_unavailable lleva 5, y un 500 manifest_degraded lleva 60, a menos que el manejador establezca un valor más específico.	Problema (application/problem+json)

POST/api/webhooks/{id}/rotate-secret¶

Rotar secreto de webhook

Reemplaza el secreto de firma y devuelve el nuevo; el secreto anterior deja de firmar de inmediato: todo intento que se firme después de confirmarse este cambio usa el secreto nuevo, y como máximo un intento por webhook que ya esté en tránsito aún puede llegar firmado con el anterior, por lo que acepte ambos durante un breve tiempo. Agrega notification.updated con details.changed [secret].

Un reintento exacto con la misma Idempotency-Key devuelve el mismo nuevo secreto por veinticuatro horas.

Autenticación: projectBearer
Cuerpo de la solicitud: ninguno
ID de operación: rotateWebhookSecret

Parámetros

Nombre	Enviar	¿Requerido?	Descripción
ScreenRig-Project	encabezado	opcional	Obsoleto por una versión. Debe ser consistente con las concesiones de proyectos JWT; añade encabezados Deprecation y Warning. Sin intercambio de token.
id	ruta	requerido
If-Match	encabezado	opcional	Revisión positiva opcional de recurso. Omitir para escribir el recurso actual; una revisión obsoleta suministrada es revision_conflict.
Idempotency-Key	encabezado	opcional	Omitir para una operación nueva. Proporcione y reutilice una clave para deduplicar reintentos; el CLI gestiona las claves automáticamente.

Plantilla y respuestas de solicitud

shell · plantilla de solicitud

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/webhooks/RESOURCE_ID/rotate-secret'

Respuestas

Estado	Significado	Cuerpo y encabezados
200	El webhook y su nuevo secreto.	Webhook con secreto (application/json); encabezados: Cache-Control
412	revision_conflict: If-Match está obsoleto; current_revision del error contiene la revisión actual.	Problema (application/problem+json)
predeterminado	Respuesta estable RFC 9457 a problemas. Un 421 server_draining lleva Retry-After de 1 segundo, un 500 not_ready o dependency_unavailable lleva 5, y un 500 manifest_degraded lleva 60, a menos que el manejador establezca un valor más específico.	Problema (application/problem+json)

POST/api/webhooks/{id}/test¶

Prueba de webhook

Agrega un evento de proyecto notification.test y pone en cola una entrega de ese evento solo para este webhook (ningún otro webhook recibe notification.test). Funciona en un webhook deshabilitado, se intenta una sola vez sin reintentos, se mide como cualquier entrega y nunca cambia el estado de fallo del webhook. Consulte el registro de entregas para ver su resultado.

Autenticación: projectBearer
Cuerpo de la solicitud: ninguno
ID de operación: testWebhook

Parámetros

Nombre	Enviar	¿Requerido?	Descripción
ScreenRig-Project	encabezado	opcional	Obsoleto por una versión. Debe ser consistente con las concesiones de proyectos JWT; añade encabezados Deprecation y Warning. Sin intercambio de token.
id	ruta	requerido
Idempotency-Key	encabezado	opcional	Omitir para una operación nueva. Proporcione y reutilice una clave para deduplicar reintentos; el CLI gestiona las claves automáticamente.

Plantilla y respuestas de solicitud

shell · plantilla de solicitud

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/webhooks/RESOURCE_ID/test'

Respuestas

Estado	Significado	Cuerpo y encabezados
202	La entrega de prueba en cola.	WebhookDelivery (application/json); encabezados: RateLimit-Policy, RateLimit
429	Problema estable rate_limited. Reintente solo después del intervalo Retry-After autorizado. Las denegaciones de ventana fija también incluyen la política RateLimit-Policy y los miembros RateLimit aplicables; las denegaciones por concurrencia y presupuesto de bytes omiten esas divulgaciones opcionales.	Problema (application/problem+json); encabezados: Retry-After, RateLimit-Policy, RateLimit
predeterminado	Respuesta estable RFC 9457 a problemas. Un 421 server_draining lleva Retry-After de 1 segundo, un 500 not_ready o dependency_unavailable lleva 5, y un 500 manifest_degraded lleva 60, a menos que el manejador establezca un valor más específico.	Problema (application/problem+json)

GET/api/webhooks/{id}/deliveries¶

Listar entregas de webhook

El registro de entregas del webhook, evento más reciente primero. Una fila por (webhook, evento); los reintentos actualizan la fila y GET .../deliveries/{delivery_id}/attempts lista sus intentos más recientes. Las filas se conservan como eventos (la retención de eventos del plan, al menos la ventana de reintento de 24 horas). Pase next_cursor como parámetro before para la siguiente página.

Autenticación: projectBearer O dashboardSession
Cuerpo de la solicitud: ninguno
ID de operación: listWebhookDeliveries

Parámetros

Nombre	Enviar	¿Requerido?	Descripción
ScreenRig-Project	encabezado	opcional	Obsoleto por una versión. Debe ser consistente con las concesiones de proyectos JWT; añade encabezados Deprecation y Warning. Sin intercambio de token.
id	ruta	requerido
before	consulta	opcional	next_cursor de la página anterior de entregas.
límite	consulta	opcional

Plantilla y respuestas de solicitud

shell · plantilla de solicitud

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/webhooks/RESOURCE_ID/deliveries'

Respuestas

Estado	Significado	Cuerpo y encabezados
200	Una página de entregas.	WebhookDeliveryList (application/json)
predeterminado	Respuesta estable RFC 9457 a problemas. Un 421 server_draining lleva Retry-After de 1 segundo, un 500 not_ready o dependency_unavailable lleva 5, y un 500 manifest_degraded lleva 60, a menos que el manejador establezca un valor más específico.	Problema (application/problem+json)

GET/api/webhooks/{id}/deliveries/{delivery_id}/attempts¶

Listar intentos de entrega de webhook

Los intentos de una entrega, los más recientes primero, los últimos 20, guardados con la fila de entrega y por tiempo indefinido. Cada uno tiene su número de intento, cuándo terminó, el estado HTTP del receptor (nulo cuando nadie respondió), la clase de error (nulo en éxito) y su duración. Nunca se guardan cuerpos ni encabezados de respuesta. Una entrega registrada antes de que se guardaran intentos no lista ninguno.

Una entrega que no es de este webhook, o un webhook de otro proyecto, es not_found.

Autenticación: projectBearer O dashboardSession
Cuerpo de la solicitud: ninguno
ID de operación: listWebhookDeliveryAttempts

Parámetros

Nombre	Enviar	¿Requerido?	Descripción
ScreenRig-Project	encabezado	opcional	Obsoleto por una versión. Debe ser consistente con las concesiones de proyectos JWT; añade encabezados Deprecation y Warning. Sin intercambio de token.
id	ruta	requerido
delivery_id	ruta	requerido	El id de una de las entregas del webhook.

Plantilla y respuestas de solicitud

shell · plantilla de solicitud

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/webhooks/RESOURCE_ID/deliveries/DELIVERY_ID/attempts'

Respuestas

Estado	Significado	Cuerpo y encabezados
200	Los intentos mantenidos de la entrega.	WebhookDeliveryAttemptList (application/json)
404	Respuesta estable RFC 9457 a problemas. Un 421 server_draining lleva Retry-After de 1 segundo, un 500 not_ready o dependency_unavailable lleva 5, y un 500 manifest_degraded lleva 60, a menos que el manejador establezca un valor más específico.	Problema (application/problem+json)
predeterminado	Respuesta estable RFC 9457 a problemas. Un 421 server_draining lleva Retry-After de 1 segundo, un 500 not_ready o dependency_unavailable lleva 5, y un 500 manifest_degraded lleva 60, a menos que el manejador establezca un valor más específico.	Problema (application/problem+json)