Entregas de webhooks
Qué salió hacia un endpoint, qué espera un reintento y qué falló, con las respuestas del receptor; una entrega se puede reintentar.
Entregas de webhooks
Objetos
WebhookDelivery
idintegerobligatorioID del registro, único entre los registros de su tipo en la tienda.
endpoint_idintegerobligatorioID del endpoint del webhook.
event_idinteger o nullobligatorioID del evento en GET /v1/events, el mismo que webhook-id de la entrega; null en un evento de prueba.
event_typestringobligatorioTipo del evento; ping en un evento de prueba.
statusstringobligatoriopending — espera un intento; succeeded — el receptor respondió 2xx; failed — se agotaron los reintentos.
- Valores:
pendingsucceededfailed
attempt_countintegerobligatorioIntentos realizados.
next_attempt_atstring (date-time) o nullobligatorioCuándo sale el próximo intento; null si la entrega está cerrada.
last_attemptobject o nullEl último intento; null antes del primero. Solo en la lista.
Campos · 7
numberintegerobligatorioNúmero del intento, desde 1.
manualbooleanobligatorioEl intento se hizo por una solicitud de reintento, no por el calendario.
started_atstring (date-time)obligatorioCuándo empezó el intento.
duration_msintegerobligatorioCuánto duró el intento, en milisegundos.
response_statusinteger o nullobligatorioEstado HTTP con el que respondió el receptor; null si no hubo respuesta.
response_bodystring o nullobligatorioComienzo del cuerpo de la respuesta del receptor; null si no hubo cuerpo.
errorstring o nullobligatorioPor qué falló el intento; null si el receptor respondió 2xx. redirect — una respuesta 3xx, las redirecciones no se siguen; http_error — otro estado; timeout — no hubo respuesta en 10 segundos; tls, connection, dns, unreachable — la red; blocked — la dirección lleva a una red interna; invalid_url — la dirección no pasa la verificación.
- Valores:
invalid_urlblockeddnsconnectiontlstimeoutunreachableredirecthttp_errornull
attemptsarray de objectTodos los intentos en orden. Solo en una entrega.
Campos · 7
numberintegerobligatorioNúmero del intento, desde 1.
manualbooleanobligatorioEl intento se hizo por una solicitud de reintento, no por el calendario.
started_atstring (date-time)obligatorioCuándo empezó el intento.
duration_msintegerobligatorioCuánto duró el intento, en milisegundos.
response_statusinteger o nullobligatorioEstado HTTP con el que respondió el receptor; null si no hubo respuesta.
response_bodystring o nullobligatorioComienzo del cuerpo de la respuesta del receptor; null si no hubo cuerpo.
errorstring o nullobligatorioPor qué falló el intento; null si el receptor respondió 2xx. redirect — una respuesta 3xx, las redirecciones no se siguen; http_error — otro estado; timeout — no hubo respuesta en 10 segundos; tls, connection, dns, unreachable — la red; blocked — la dirección lleva a una red interna; invalid_url — la dirección no pasa la verificación.
- Valores:
invalid_urlblockeddnsconnectiontlstimeoutunreachableredirecthttp_errornull
created_atstring (date-time)obligatorioCuándo se creó el registro.
updated_atstring (date-time)obligatorioCuándo cambió el registro por última vez.
Endpoints
Entregas de un endpoint de webhook: lo enviado, lo que espera un reintento y lo que falló
get/webhook-endpoints/{endpoint}/deliveries
Scope: webhooks:read
Parámetros
Ruta
endpointintegerobligatorioID del endpoint del webhook.
Query
limitintegerTamaño de página: hasta 250 registros; 50 por defecto.
- Mínimo:
- 1
- Máximo:
- 250
cursorstringCursor opaco: next_cursor de la página anterior, o sync_cursor de la última página guardado por la sincronización anterior. El listado va en orden de confirmación, así que el cursor de sincronización devuelve luego solo lo que cambió después de él.
- Largo máximo:
- 4096
updated_sincestring (date-time)Solo los registros cambiados después de este momento, ISO 8601 con zona horaria. Un filtro de la primera sincronización; después se sigue con el cursor.
- Patrón:
^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,6})?(Z|[+-]\d{2}:\d{2})$
statusstringSolo las entregas en este estado.
- Valores:
pendingsucceededfailed
Respuestas
200Éxito
application/json
Registros de la página.
deletedarray de objectobligatorioRegistros borrados de la base desde el cursor, como marcas de eliminación: solo con include_deleted=true en la continuación por el cursor de sincronización.
Campos · 2
idintegerobligatorioID del registro borrado.
deleted_atstring (date-time)obligatorioCuándo se borró el registro.
next_cursorstring o nullobligatorioCursor de la página siguiente; null en la última.
has_morebooleanobligatoriotrue si hay una página siguiente.
sync_cursorstring o nullobligatorioEn la última página — el cursor desde el que continuar más tarde: con él llega solo lo que cambió después de esta página. null en las demás.
401Falta el token, es inválido, venció o fue revocado
Encabezados
WWW-AuthenticatestringobligatorioEsquema de autenticación (RFC 6750).
- Ejemplo:
Bearer
application/problem+json
Devuelve Problem
403El plan, la dirección IP o los scopes del token no permiten la solicitud
Encabezados
WWW-AuthenticatestringEsquema de autenticación (RFC 6750).
- Ejemplo:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Devuelve ForbiddenProblem
404El objeto no existe o no está disponible para la aplicación
application/problem+json
Devuelve Problem
410El cursor de sincronización supera el plazo de conservación de eliminaciones o se emitió antes de restaurar la base de datos
application/problem+json
Devuelve Problem
422Un parámetro es inválido o desconocido
application/problem+json
Devuelve ValidationProblem
429Se agotó el límite de solicitudes
Encabezados
Retry-AfterintegerobligatorioSegundos de espera antes de reintentar.
- Mínimo:
- 0
application/problem+json
Devuelve RateLimitProblem
503La tienda no está disponible por ahora
Encabezados
Retry-AfterintegerSegundos de espera antes de reintentar.
- Mínimo:
- 0
application/problem+json
Devuelve Problem
Errores de este endpoint
Los errores comunes, como token, acceso, validación de la entrada y límite de solicitudes, pueden venir de cualquier endpoint; están en el catálogo: Errores
curl "https://api.saleya.app/v1/webhook-endpoints/{endpoint}/deliveries" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"data": [
{
"id": 0,
"endpoint_id": 0,
"event_id": 0,
"event_type": "string",
"status": "pending",
"attempt_count": 0,
"next_attempt_at": "2026-01-15T12:00:00Z",
"last_attempt": {
"number": 0,
"manual": true,
"started_at": "2026-01-15T12:00:00Z",
"duration_ms": 0,
"response_status": 0,
"response_body": "string",
"error": "invalid_url"
},
"attempts": [
{
"number": 0,
"manual": true,
"started_at": "2026-01-15T12:00:00Z",
"duration_ms": 0,
"response_status": 0,
"response_body": "string",
"error": "invalid_url"
}
],
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z"
}
],
"deleted": [
{
"id": 0,
"deleted_at": "2026-01-15T12:00:00Z"
}
],
"next_cursor": "string",
"has_more": true,
"sync_cursor": "string"
}Una entrega de webhook con todos sus intentos y respuestas del receptor
get/webhook-deliveries/{delivery}
Scope: webhooks:read
Parámetros
Ruta
deliveryintegerobligatorioID de la entrega del webhook.
Respuestas
200Éxito
application/json
Devuelve WebhookDelivery
401Falta el token, es inválido, venció o fue revocado
Encabezados
WWW-AuthenticatestringobligatorioEsquema de autenticación (RFC 6750).
- Ejemplo:
Bearer
application/problem+json
Devuelve Problem
403El plan, la dirección IP o los scopes del token no permiten la solicitud
Encabezados
WWW-AuthenticatestringEsquema de autenticación (RFC 6750).
- Ejemplo:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Devuelve ForbiddenProblem
404El objeto no existe o no está disponible para la aplicación
application/problem+json
Devuelve Problem
422Un parámetro es inválido o desconocido
application/problem+json
Devuelve ValidationProblem
429Se agotó el límite de solicitudes
Encabezados
Retry-AfterintegerobligatorioSegundos de espera antes de reintentar.
- Mínimo:
- 0
application/problem+json
Devuelve RateLimitProblem
503La tienda no está disponible por ahora
Encabezados
Retry-AfterintegerSegundos de espera antes de reintentar.
- Mínimo:
- 0
application/problem+json
Devuelve Problem
Los errores comunes, como token, acceso, validación de la entrada y límite de solicitudes, pueden venir de cualquier endpoint; están en el catálogo: Errores
curl "https://api.saleya.app/v1/webhook-deliveries/{delivery}" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"id": 0,
"endpoint_id": 0,
"event_id": 0,
"event_type": "string",
"status": "pending",
"attempt_count": 0,
"next_attempt_at": "2026-01-15T12:00:00Z",
"last_attempt": {
"number": 0,
"manual": true,
"started_at": "2026-01-15T12:00:00Z",
"duration_ms": 0,
"response_status": 0,
"response_body": "string",
"error": "invalid_url"
},
"attempts": [
{
"number": 0,
"manual": true,
"started_at": "2026-01-15T12:00:00Z",
"duration_ms": 0,
"response_status": 0,
"response_body": "string",
"error": "invalid_url"
}
],
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z"
}Enviar al endpoint el evento de prueba ping — un intento firmado con el secreto actual
post/webhook-endpoints/{endpoint}/test
Scope: webhooks:write
Parámetros
Ruta
endpointintegerobligatorioID del endpoint del webhook.
Encabezado
Idempotency-KeystringClave única del intento, por ejemplo un UUID. Un reintento con la misma clave y el mismo cuerpo recibe la respuesta guardada en vez de escribir dos veces. Las claves duran 24 horas.
- Largo mínimo:
- 1
- Largo máximo:
- 255
- Ejemplo:
8e03978e-40d5-43e8-bc93-6894a57f9324
Respuestas
202Aceptado: el resultado está en la dirección de Location
Encabezados
Idempotent-Replayedstringtrue cuando es la respuesta guardada de una solicitud anterior con el mismo Idempotency-Key.
- Valores:
true
Locationstring (uri)obligatorioDirección del registro creado; en una solicitud aceptada (202), la dirección donde seguir su resultado.
application/json
Devuelve WebhookDelivery
401Falta el token, es inválido, venció o fue revocado
Encabezados
WWW-AuthenticatestringobligatorioEsquema de autenticación (RFC 6750).
- Ejemplo:
Bearer
application/problem+json
Devuelve Problem
403El plan, la dirección IP o los scopes del token no permiten la solicitud
Encabezados
WWW-AuthenticatestringEsquema de autenticación (RFC 6750).
- Ejemplo:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Devuelve ForbiddenProblem
404El objeto no existe o no está disponible para la aplicación
application/problem+json
Devuelve Problem
409Hay una solicitud en curso con la misma clave de idempotencia, los datos cambiaron después de leerlos, el ID externo pertenece a otro registro, se alcanzó el límite del plan o de endpoints de webhook, o el cambio necesita consentir sus consecuencias
Encabezados
Retry-AfterintegerSegundos de espera antes de reintentar.
- Mínimo:
- 0
application/problem+json
Devuelve ConflictProblem
422Un parámetro es inválido o desconocido
application/problem+json
Devuelve ValidationProblem
429Se agotó el límite de solicitudes
Encabezados
Retry-AfterintegerobligatorioSegundos de espera antes de reintentar.
- Mínimo:
- 0
application/problem+json
Devuelve RateLimitProblem
503La tienda no está disponible por ahora
Encabezados
Retry-AfterintegerSegundos de espera antes de reintentar.
- Mínimo:
- 0
application/problem+json
Devuelve Problem
Errores de este endpoint
- 409
idempotency_key_in_useHay una solicitud en curso con esta clave - 422
idempotency_key_reusedLa clave de idempotencia ya se usó - 422
invalid_idempotency_keyLa clave de idempotencia no es válida
Los errores comunes, como token, acceso, validación de la entrada y límite de solicitudes, pueden venir de cualquier endpoint; están en el catálogo: Errores
curl -X POST "https://api.saleya.app/v1/webhook-endpoints/{endpoint}/test" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"id": 0,
"endpoint_id": 0,
"event_id": 0,
"event_type": "string",
"status": "pending",
"attempt_count": 0,
"next_attempt_at": "2026-01-15T12:00:00Z",
"last_attempt": {
"number": 0,
"manual": true,
"started_at": "2026-01-15T12:00:00Z",
"duration_ms": 0,
"response_status": 0,
"response_body": "string",
"error": "invalid_url"
},
"attempts": [
{
"number": 0,
"manual": true,
"started_at": "2026-01-15T12:00:00Z",
"duration_ms": 0,
"response_status": 0,
"response_body": "string",
"error": "invalid_url"
}
],
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z"
}Reintentar la entrega ahora, con el mismo cuerpo y el mismo webhook-id
post/webhook-deliveries/{delivery}/retry
Scope: webhooks:write
Parámetros
Ruta
deliveryintegerobligatorioID de la entrega del webhook.
Encabezado
Idempotency-KeystringClave única del intento, por ejemplo un UUID. Un reintento con la misma clave y el mismo cuerpo recibe la respuesta guardada en vez de escribir dos veces. Las claves duran 24 horas.
- Largo mínimo:
- 1
- Largo máximo:
- 255
- Ejemplo:
8e03978e-40d5-43e8-bc93-6894a57f9324
Respuestas
202Aceptado: el resultado está en la dirección de Location
Encabezados
Idempotent-Replayedstringtrue cuando es la respuesta guardada de una solicitud anterior con el mismo Idempotency-Key.
- Valores:
true
Locationstring (uri)obligatorioDirección del registro creado; en una solicitud aceptada (202), la dirección donde seguir su resultado.
application/json
Devuelve WebhookDelivery
401Falta el token, es inválido, venció o fue revocado
Encabezados
WWW-AuthenticatestringobligatorioEsquema de autenticación (RFC 6750).
- Ejemplo:
Bearer
application/problem+json
Devuelve Problem
403El plan, la dirección IP o los scopes del token no permiten la solicitud
Encabezados
WWW-AuthenticatestringEsquema de autenticación (RFC 6750).
- Ejemplo:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Devuelve ForbiddenProblem
404El objeto no existe o no está disponible para la aplicación
application/problem+json
Devuelve Problem
409Hay una solicitud en curso con la misma clave de idempotencia, los datos cambiaron después de leerlos, el ID externo pertenece a otro registro, se alcanzó el límite del plan o de endpoints de webhook, o el cambio necesita consentir sus consecuencias
Encabezados
Retry-AfterintegerSegundos de espera antes de reintentar.
- Mínimo:
- 0
application/problem+json
Devuelve ConflictProblem
422Un parámetro es inválido o desconocido
application/problem+json
Devuelve ValidationProblem
429Se agotó el límite de solicitudes
Encabezados
Retry-AfterintegerobligatorioSegundos de espera antes de reintentar.
- Mínimo:
- 0
application/problem+json
Devuelve RateLimitProblem
503La tienda no está disponible por ahora
Encabezados
Retry-AfterintegerSegundos de espera antes de reintentar.
- Mínimo:
- 0
application/problem+json
Devuelve Problem
Errores de este endpoint
- 409
idempotency_key_in_useHay una solicitud en curso con esta clave - 422
idempotency_key_reusedLa clave de idempotencia ya se usó - 422
invalid_idempotency_keyLa clave de idempotencia no es válida
Los errores comunes, como token, acceso, validación de la entrada y límite de solicitudes, pueden venir de cualquier endpoint; están en el catálogo: Errores
curl -X POST "https://api.saleya.app/v1/webhook-deliveries/{delivery}/retry" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"id": 0,
"endpoint_id": 0,
"event_id": 0,
"event_type": "string",
"status": "pending",
"attempt_count": 0,
"next_attempt_at": "2026-01-15T12:00:00Z",
"last_attempt": {
"number": 0,
"manual": true,
"started_at": "2026-01-15T12:00:00Z",
"duration_ms": 0,
"response_status": 0,
"response_body": "string",
"error": "invalid_url"
},
"attempts": [
{
"number": 0,
"manual": true,
"started_at": "2026-01-15T12:00:00Z",
"duration_ms": 0,
"response_status": 0,
"response_body": "string",
"error": "invalid_url"
}
],
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z"
}