Webhooks de la Organization

Gestiona los endpoints de webhook en toda la Organization desde el Dashboard — configuraciones, entregas y rotación de secretos.

Estos endpoints sustentan la pantalla de webhooks de la Organization: registrar endpoints, inspeccionar entregas y reintentos, y rotar secretos de firma, en todos los Merchants de la Organization.

El secreto de firma (whsec_…) se muestra solo cuando se crea o se rota — captúralo en ese momento. Cada entrega está firmada; verifica el X-Tokeflow-Signature antes de actuar. Consulta Verificación de firmas.

Estos endpoints impulsan la interfaz del Tokeflow Dashboard a nivel de la Organization. Están autenticados por sesión (JWT bearer) — el token proviene de iniciar sesión en el Dashboard, no de una clave de API sk_/pk_. Las solicitudes también incluyen el header x-organization-id, y el usuario que inició sesión debe ser miembro de esa Organization.

El objeto de configuración de webhook

Devuelto por los endpoints de listado y de recuperación de esta página.

Campo	Tipo	Descripción
`id`	string	Identificador único de la configuración de webhook.
`merchant_id`	string	ID de Merchant que posee 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/org/webhooks`

Org

Auth: Dashboard session (JWT bearer). Se requiere membresía de la Organization.

Lista las configuraciones de webhook del Merchant.

Parámetros de consulta

Campo	Tipo	Obligatorio	Descripción
`page`	number	No	Número de página (indexado desde 1). Predeterminado `1`, mín. `1`.
`limit`	number	No	Número de elementos por página. Predeterminado `20`, mín. `1`, máx. `100`.

Ejemplo de solicitud

curl -G https://api.tokeflow.com/api/v1/org/webhooks \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-organization-id: org_4b21e7c3" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=20"

Ejemplo de respuesta — 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/org/webhooks`

Org

Auth: Dashboard session (JWT bearer). Se requiere membresía de la Organization.

Crea una nueva configuración de webhook.

Campos de la solicitud

Campo	Tipo	Obligatorio	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 suscribir. Si no se proporciona, se enviarán todos los eventos.

Ejemplo de solicitud

curl -X POST https://api.tokeflow.com/api/v1/org/webhooks \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-organization-id: org_4b21e7c3" \
  -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"
    ]
  }'

Ejemplo de respuesta — 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..."
}

GET`/api/v1/org/webhooks/deliveries`

Org

Auth: Dashboard session (JWT bearer). Se requiere membresía de la Organization.

Lista todas las entregas de webhook del Merchant.

Parámetros de consulta

Campo	Tipo	Obligatorio	Descripción
`page`	number	No	Número de página (indexado desde 1). Predeterminado `1`, mín. `1`.
`limit`	number	No	Número de elementos por página. Predeterminado `20`, mín. `1`, máx. `100`.
`status`	string	Sí	—

Ejemplo de solicitud

curl -G https://api.tokeflow.com/api/v1/org/webhooks/deliveries \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-organization-id: org_4b21e7c3" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=20" \
  --data-urlencode "status=active"

Ejemplo de respuesta — 200

{
  "data": [
    {
      "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"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 42,
    "total_pages": 3,
    "has_next": true,
    "has_prev": false
  }
}

GET`/api/v1/org/webhooks/webhook-deliveries/:delivery_id`

Org

Auth: Dashboard session (JWT bearer). Se requiere membresía de la Organization.

Obtiene una entrega de webhook específica.

Parámetros de ruta

Campo	Tipo	Obligatorio	Descripción
`delivery_id`	string	Sí	—

Ejemplo de solicitud

curl https://api.tokeflow.com/api/v1/org/webhooks/webhook-deliveries/123 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-organization-id: org_4b21e7c3"

Ejemplo de respuesta — 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"
}

DELETE`/api/v1/org/webhooks/:webhook_id`

Org

Auth: Dashboard session (JWT bearer). Se requiere membresía de la Organization.

Elimina una configuración de webhook.

Parámetros de ruta

Campo	Tipo	Obligatorio	Descripción
`webhook_id`	string	Sí	—

Ejemplo de solicitud

curl -X DELETE https://api.tokeflow.com/api/v1/org/webhooks/whk_3e9d1f42 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-organization-id: org_4b21e7c3"

Ejemplo de respuesta — 204 No Content

Se devuelve un cuerpo vacío en caso de éxito.

GET`/api/v1/org/webhooks/:webhook_id`

Org

Auth: Dashboard session (JWT bearer). Se requiere membresía de la Organization.

Obtiene la configuración de webhook por ID.

Parámetros de ruta

Campo	Tipo	Obligatorio	Descripción
`webhook_id`	string	Sí	—

Ejemplo de solicitud

curl https://api.tokeflow.com/api/v1/org/webhooks/whk_3e9d1f42 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-organization-id: org_4b21e7c3"

Ejemplo de respuesta — 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/org/webhooks/:webhook_id`

Org

Auth: Dashboard session (JWT bearer). Se requiere membresía de la Organization.

Actualiza una configuración de webhook.

Parámetros de ruta

Campo	Tipo	Obligatorio	Descripción
`webhook_id`	string	Sí	—

Campos de la solicitud

Campo	Tipo	Obligatorio	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 suscribir.
`is_active`	boolean	No	Si esta configuración de webhook está activa.

Ejemplo de solicitud

curl -X PATCH https://api.tokeflow.com/api/v1/org/webhooks/whk_3e9d1f42 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-organization-id: org_4b21e7c3" \
  -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
  }'

Ejemplo de respuesta — 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/org/webhooks/:webhook_id/deliveries`

Org

Auth: Dashboard session (JWT bearer). Se requiere membresía de la Organization.

Lista las entregas de webhook de un webhook específico.

Parámetros de ruta

Campo	Tipo	Obligatorio	Descripción
`webhook_id`	string	Sí	—

Parámetros de consulta

Campo	Tipo	Obligatorio	Descripción
`page`	number	No	Número de página (indexado desde 1). Predeterminado `1`, mín. `1`.
`limit`	number	No	Número de elementos por página. Predeterminado `20`, mín. `1`, máx. `100`.
`status`	string	No	Filtra por el estado de la entrega
`from`	string	No	Timestamp inicial (formato ISO 8601) - filtra entregas después de este momento
`to`	string	No	Timestamp final (formato ISO 8601) - filtra entregas antes de este momento

Ejemplo de solicitud

curl -G https://api.tokeflow.com/api/v1/org/webhooks/whk_3e9d1f42/deliveries \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-organization-id: org_4b21e7c3" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=20" \
  --data-urlencode "status=failed" \
  --data-urlencode "from=2024-01-01T00:00:00Z"

Ejemplo de respuesta — 200

{
  "data": [
    {
      "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"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 42,
    "total_pages": 3,
    "has_next": true,
    "has_prev": false
  }
}

POST`/api/v1/org/webhooks/:webhook_id/rotate-secret`

Org

Auth: Dashboard session (JWT bearer). Se requiere membresía de la Organization.

Rota el secreto del webhook.

Parámetros de ruta

Campo	Tipo	Obligatorio	Descripción
`webhook_id`	string	Sí	—

Ejemplo de solicitud

curl -X POST https://api.tokeflow.com/api/v1/org/webhooks/whk_3e9d1f42/rotate-secret \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-organization-id: org_4b21e7c3"

Ejemplo de respuesta — 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..."
}

POST`/api/v1/org/webhooks/:webhook_id/test`

Org

Auth: Dashboard session (JWT bearer). Se requiere membresía de la Organization.

Prueba una configuración de webhook enviando un evento de prueba.

Parámetros de ruta

Campo	Tipo	Obligatorio	Descripción
`webhook_id`	string	Sí	—

Ejemplo de solicitud

curl -X POST https://api.tokeflow.com/api/v1/org/webhooks/whk_3e9d1f42/test \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-organization-id: org_4b21e7c3"

Ejemplo de respuesta — 200

{
  "success": true,
  "message": "Operation completed successfully",
  "http_status": 200
}

Errores

Los errores usan el envoltorio estándar. Los casos más comunes aquí:

HTTP	Significado
`400`	Parámetros inválidos o un estado que no permite esta operación.
`401`	Token de sesión del Dashboard ausente, expirado o inválido.
`403`	Autenticado, pero el usuario que inició sesión no tiene acceso a esta entidad.
`404`	El registro no existe o no es visible para esta entidad.

Webhooks de la Organization

El objeto de configuración de webhook

Endpoints

GET`/api/v1/org/webhooks`

POST`/api/v1/org/webhooks`

GET`/api/v1/org/webhooks/deliveries`

GET`/api/v1/org/webhooks/webhook-deliveries/:delivery_id`

DELETE`/api/v1/org/webhooks/:webhook_id`

GET`/api/v1/org/webhooks/:webhook_id`

PATCH`/api/v1/org/webhooks/:webhook_id`

GET`/api/v1/org/webhooks/:webhook_id/deliveries`

POST`/api/v1/org/webhooks/:webhook_id/rotate-secret`

POST`/api/v1/org/webhooks/:webhook_id/test`

Errores

Relacionados

En esta página

Webhooks de la Organization

El objeto de configuración de webhook

Endpoints

GET/api/v1/org/webhooks

POST/api/v1/org/webhooks

GET/api/v1/org/webhooks/deliveries

GET/api/v1/org/webhooks/webhook-deliveries/:delivery_id

DELETE/api/v1/org/webhooks/:webhook_id

GET/api/v1/org/webhooks/:webhook_id

PATCH/api/v1/org/webhooks/:webhook_id

GET/api/v1/org/webhooks/:webhook_id/deliveries

POST/api/v1/org/webhooks/:webhook_id/rotate-secret

POST/api/v1/org/webhooks/:webhook_id/test

Errores

Relacionados

En esta página

GET`/api/v1/org/webhooks`

POST`/api/v1/org/webhooks`

GET`/api/v1/org/webhooks/deliveries`

GET`/api/v1/org/webhooks/webhook-deliveries/:delivery_id`

DELETE`/api/v1/org/webhooks/:webhook_id`

GET`/api/v1/org/webhooks/:webhook_id`

PATCH`/api/v1/org/webhooks/:webhook_id`

GET`/api/v1/org/webhooks/:webhook_id/deliveries`

POST`/api/v1/org/webhooks/:webhook_id/rotate-secret`

POST`/api/v1/org/webhooks/:webhook_id/test`