Endpoints de webhook
Registra y gestiona endpoints de webhook de forma programática — crea configuraciones, inspecciona entregas y rota el secreto de firma usado para verificar eventos.
Un endpoint de webhook es una URL a la que Tokeflow entrega eventos firmados, junto con la configuración que lo rige: a qué tipos de evento está suscrito, si está activo, y el secreto de firma usado para probar que cada entrega provino de Tokeflow.
Estos endpoints te permiten gestionar esa configuración desde tu backend en lugar del Dashboard — útil cuando aprovisionas Merchants de forma programática o necesitas rotar secretos según un cronograma. Toda entrega que envía Tokeflow está firmada; siempre verifica la firma antes de actuar sobre un evento. Consulta Verificación de firmas de webhook.
El secreto de firma (whsec_…) se devuelve solo cuando creas el endpoint o rotas el secreto. Guárdalo en un gestor de secretos en ese momento — no se puede recuperar después. Rotar invalida el secreto anterior, así que despliega el nuevo antes de rotar, o acepta una breve ventana de verificaciones fallidas.
El objeto de endpoint de webhook
Una configuración de webhook tal como la devuelven los endpoints de creación, listado y consulta.
| Campo | Tipo | Descripción |
|---|---|---|
id | string | Identificador único de la configuración de webhook. |
merchant_id | string | ID del Merchant propietario de esta configuración de webhook. |
url | string | La URL a la que se enviarán los eventos de webhook. |
description | string | null | Descripción de esta configuración de webhook. |
event_filter | array | null | Lista de tipos de evento suscritos. Null significa todos los eventos. |
is_active | boolean | Si esta configuración de webhook está activa. |
created_at | string | Cuándo se creó la configuración de webhook. (ISO 8601 UTC). |
updated_at | string | Cuándo se actualizó por última vez la configuración de webhook. (ISO 8601 UTC). |
last_triggered_at | string | null | Cuándo se activó el webhook por última vez (entrega más reciente). (ISO 8601 UTC). |
Endpoints
GET/api/v1/merchants/:merchant_id/webhook-configs
Auth: Clave de Organization (con merchant_id) o clave de Merchant.
Lista las configuraciones de webhook.
Parámetros de ruta
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
merchant_id | string | Sí | — |
Parámetros de consulta
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
page | number | No | Número de página (indexado desde 1). Por defecto 1, mín. 1. |
limit | number | No | Cantidad de elementos por página. Por defecto 20, mín. 1, máx. 100. |
Solicitud de ejemplo
curl -G https://api.tokeflow.com/api/v1/merchants/mrc_8a3f12d9/webhook-configs \
-H "Authorization: Bearer sk_live_mer_…" \
--data-urlencode "page=1" \
--data-urlencode "limit=20"Respuesta de ejemplo — 200
{
"data": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"merchant_id": "550e8400-e29b-41d4-a716-446655440001",
"url": "https://api.example.com/webhooks/payments",
"description": "Production payment notifications",
"event_filter": [
"transaction.authorized",
"transaction.failed",
"transaction.refunded"
],
"is_active": true,
"created_at": "2024-01-15T10:30:00.000Z",
"updated_at": "2024-01-15T10:30:00.000Z",
"last_triggered_at": "2024-01-15T10:30:00.000Z"
}
],
"meta": {
"page": 1,
"limit": 20,
"total": 42,
"total_pages": 3,
"has_next": true,
"has_prev": false
}
}POST/api/v1/merchants/:merchant_id/webhook-configs
Auth: Clave de Organization (con merchant_id) o clave de Merchant.
Crea una configuración de webhook.
Parámetros de ruta
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
merchant_id | string | Sí | — |
Campos de la solicitud
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
url | string | Sí | La URL a la que se enviarán los eventos de webhook. |
description | string | No | Descripción opcional para esta configuración de webhook. |
event_filter | array | No | Lista de tipos de evento a los que suscribirse. Si no se proporciona, se enviarán todos los eventos. |
Solicitud de ejemplo
curl -X POST https://api.tokeflow.com/api/v1/merchants/mrc_8a3f12d9/webhook-configs \
-H "Authorization: Bearer sk_live_mer_…" \
-H "Content-Type: application/json" \
-d '{
"url": "https://api.example.com/webhooks/payments",
"description": "Production payment notifications",
"event_filter": [
"transaction.authorized",
"transaction.failed",
"transaction.refunded"
]
}'Respuesta de ejemplo — 201
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"merchant_id": "550e8400-e29b-41d4-a716-446655440001",
"url": "https://api.example.com/webhooks/payments",
"description": "Production payment notifications",
"event_filter": [
"transaction.authorized",
"transaction.failed",
"transaction.refunded"
],
"is_active": true,
"created_at": "2024-01-15T10:30:00.000Z",
"updated_at": "2024-01-15T10:30:00.000Z",
"last_triggered_at": "2024-01-15T10:30:00.000Z",
"secret": "whsec_abc123def456..."
}DELETE/api/v1/merchants/:merchant_id/webhook-configs/:webhook_id
Auth: Clave de Organization (con merchant_id) o clave de Merchant.
Elimina una configuración de webhook.
Parámetros de ruta
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
merchant_id | string | Sí | — |
webhook_id | string | Sí | — |
Solicitud de ejemplo
curl -X DELETE https://api.tokeflow.com/api/v1/merchants/mrc_8a3f12d9/webhook-configs/whk_3e9d1f42 \
-H "Authorization: Bearer sk_live_mer_…"Respuesta de ejemplo — 204 No Content
Se devuelve un cuerpo vacío cuando la operación es exitosa.
GET/api/v1/merchants/:merchant_id/webhook-configs/:webhook_id
Auth: Clave de Organization (con merchant_id) o clave de Merchant.
Obtiene una configuración de webhook.
Parámetros de ruta
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
merchant_id | string | Sí | — |
webhook_id | string | Sí | — |
Solicitud de ejemplo
curl https://api.tokeflow.com/api/v1/merchants/mrc_8a3f12d9/webhook-configs/whk_3e9d1f42 \
-H "Authorization: Bearer sk_live_mer_…"Respuesta de ejemplo — 200
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"merchant_id": "550e8400-e29b-41d4-a716-446655440001",
"url": "https://api.example.com/webhooks/payments",
"description": "Production payment notifications",
"event_filter": [
"transaction.authorized",
"transaction.failed",
"transaction.refunded"
],
"is_active": true,
"created_at": "2024-01-15T10:30:00.000Z",
"updated_at": "2024-01-15T10:30:00.000Z",
"last_triggered_at": "2024-01-15T10:30:00.000Z"
}PATCH/api/v1/merchants/:merchant_id/webhook-configs/:webhook_id
Auth: Clave de Organization (con merchant_id) o clave de Merchant.
Actualiza una configuración de webhook.
Parámetros de ruta
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
merchant_id | string | Sí | — |
webhook_id | string | Sí | — |
Campos de la solicitud
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
url | string | No | La URL a la que se enviarán los eventos de webhook. |
description | string | No | Descripción opcional para esta configuración de webhook. |
event_filter | array | No | Lista de tipos de evento a los que suscribirse. |
is_active | boolean | No | Si esta configuración de webhook está activa. |
Solicitud de ejemplo
curl -X PATCH https://api.tokeflow.com/api/v1/merchants/mrc_8a3f12d9/webhook-configs/whk_3e9d1f42 \
-H "Authorization: Bearer sk_live_mer_…" \
-H "Content-Type: application/json" \
-d '{
"url": "https://api.example.com/webhooks/payments",
"description": "Production payment notifications",
"event_filter": [
"transaction.authorized",
"transaction.failed",
"transaction.refunded"
],
"is_active": true
}'Respuesta de ejemplo — 200
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"merchant_id": "550e8400-e29b-41d4-a716-446655440001",
"url": "https://api.example.com/webhooks/payments",
"description": "Production payment notifications",
"event_filter": [
"transaction.authorized",
"transaction.failed",
"transaction.refunded"
],
"is_active": true,
"created_at": "2024-01-15T10:30:00.000Z",
"updated_at": "2024-01-15T10:30:00.000Z",
"last_triggered_at": "2024-01-15T10:30:00.000Z"
}GET/api/v1/merchants/:merchant_id/webhook-deliveries
Auth: Clave de Organization (con merchant_id) o clave de Merchant.
Lista el historial de entregas de webhook.
Parámetros de ruta
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
merchant_id | string | Sí | — |
Parámetros de consulta
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
page | number | No | Número de página (indexado desde 1). Por defecto 1, mín. 1. |
limit | number | No | Cantidad de elementos por página. Por defecto 20, mín. 1, máx. 100. |
status | string | No | Filtrar por estado de entrega |
from | string | No | Marca de tiempo desde (formato ISO 8601) - filtra entregas posteriores a este momento |
to | string | No | Marca de tiempo hasta (formato ISO 8601) - filtra entregas anteriores a este momento |
Solicitud de ejemplo
curl -G https://api.tokeflow.com/api/v1/merchants/mrc_8a3f12d9/webhook-deliveries \
-H "Authorization: Bearer sk_live_mer_…" \
--data-urlencode "page=1" \
--data-urlencode "limit=20" \
--data-urlencode "status=failed" \
--data-urlencode "from=2024-01-01T00:00:00Z"Respuesta de ejemplo — 200
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"merchant_id": "550e8400-e29b-41d4-a716-446655440001",
"merchant_webhook_config_id": "550e8400-e29b-41d4-a716-446655440002",
"payment_transaction_id": "550e8400-e29b-41d4-a716-446655440003",
"order_id": "550e8400-e29b-41d4-a716-446655440004",
"event_type": "transaction.authorized",
"payload": {
"event": "transaction.authorized",
"data": {
"transaction_id": "..."
}
},
"target_url": "https://api.example.com/webhooks/payments",
"attempt_number": 1,
"http_status_code": 200,
"response_body": "{\"received\": true}",
"status": "success",
"next_retry_at": "2024-01-15T10:35:00.000Z",
"created_at": "2024-01-15T10:30:00.000Z",
"sent_at": "2024-01-15T10:30:01.000Z"
}POST/api/v1/merchants/:merchant_id/webhooks/:webhook_id/rotate-secret
Auth: Clave de Organization (con merchant_id) o clave de Merchant.
Rota el secreto del webhook.
Parámetros de ruta
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
merchant_id | string | Sí | — |
webhook_id | string | Sí | — |
Solicitud de ejemplo
curl -X POST https://api.tokeflow.com/api/v1/merchants/mrc_8a3f12d9/webhooks/whk_3e9d1f42/rotate-secret \
-H "Authorization: Bearer sk_live_mer_…"Respuesta de ejemplo — 200
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"merchant_id": "550e8400-e29b-41d4-a716-446655440001",
"url": "https://api.example.com/webhooks/payments",
"description": "Production payment notifications",
"event_filter": [
"transaction.authorized",
"transaction.failed",
"transaction.refunded"
],
"is_active": true,
"created_at": "2024-01-15T10:30:00.000Z",
"updated_at": "2024-01-15T10:30:00.000Z",
"last_triggered_at": "2024-01-15T10:30:00.000Z",
"secret": "whsec_abc123def456..."
}Errores
Los errores usan el envoltorio estándar. Los casos más comunes aquí:
| HTTP | type | Causa típica |
|---|---|---|
400 | validation_error | Falta un campo requerido, o una operación que el estado actual no permite. |
401 | authentication_error | Clave de API faltante o inválida. |
403 | authorization_error | La clave carece del alcance requerido. |
404 | not_found_error | El recurso no existe o no pertenece a esta entidad. |
429 | rate_limit_error | Límite de tasa excedido — reintenta con retroceso exponencial. |
Consulta Errores para ver el catálogo completo.