Saltar al contenido principal
POST
/
v1
/
webhooks
Crear un Registro de Webhook
curl --request POST \
  --url https://plugin-br-bank-transfer.sandbox.lerian.net/v1/webhooks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency: <x-idempotency>' \
  --data '
{
  "name": "Operations webhook",
  "endpointUrl": "https://hooks.example.com/transfer-events",
  "enabled": true,
  "eventTypes": [
    "transfer.completed",
    "transfer.rejected"
  ]
}
'
{ "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Operations webhook", "endpointUrl": "https://hooks.example.com/transfer-events", "enabled": true, "eventTypes": [ "transfer.completed", "transfer.rejected" ], "signingSecret": "whsec_example_not_a_real_secret", "createdAt": "2026-02-01T15:30:00Z", "updatedAt": "2026-02-01T15:30:00Z" }

Autorizaciones

​
Authorization
string
header
requerido

Autenticación mediante token JWT Bearer. El tenantId se deriva del token bearer o del contexto autenticado de la solicitud y no se proporciona a través de X-Organization-Id.

Encabezados

​
X-Idempotency
string
requerido

Clave de idempotencia requerida para reintentos seguros. Utilice un UUID v4 o un identificador de negocio único. Si se envía la misma clave nuevamente y la solicitud original ya fue procesada, se devuelve la respuesta almacenada en caché.

Consulte Reintentos e idempotencia para más detalles.

Maximum string length: 255

Cuerpo

application/json
​
name
string
requerido

Un nombre legible para el registro.

Ejemplo:

"Operations webhook"

​
endpointUrl
string<uri>
requerido

El endpoint que recibe las entregas de eventos. Debe ser una URL HTTPS.

Pattern: ^https://
Ejemplo:

"https://hooks.example.com/transfer-events"

​
enabled
boolean

Si el registro está activo. Por defecto es true cuando se omite.

Ejemplo:

true

​
eventTypes
string[]

Los tipos de evento a los que se suscribe este endpoint. Cuando se omite, el registro recibe todos los tipos de evento. Utilice el endpoint Listar Tipos de Evento de Webhook para conocer los valores aceptados.

Maximum array length: 64
Ejemplo:
["transfer.completed", "transfer.rejected"]

Respuesta

Indica que el registro de webhook fue creado. El signingSecret solo se devuelve en esta respuesta.

Las llamadas repetidas con la misma clave X-Idempotency reproducen la respuesta en caché.

Consulte Reintentos e idempotencia para más detalles.

​
id
string<uuid>
requerido

El identificador único del registro de webhook.

Ejemplo:

"550e8400-e29b-41d4-a716-446655440000"

​
name
string
requerido

El nombre legible del registro.

Ejemplo:

"Operations webhook"

​
endpointUrl
string<uri>
requerido

El endpoint HTTPS que recibe las entregas de eventos.

Ejemplo:

"https://hooks.example.com/transfer-events"

​
enabled
boolean
requerido

Si el registro está activo.

Ejemplo:

true

​
createdAt
string<date-time>
requerido

La marca de tiempo de cuando se creó el registro.

Ejemplo:

"2026-02-01T15:30:00Z"

​
updatedAt
string<date-time>
requerido

La marca de tiempo de la última actualización.

Ejemplo:

"2026-02-01T15:30:00Z"

​
signingSecret
string
requerido

El secreto de firma generado por el servidor, devuelto únicamente en esta respuesta. Almacénelo de forma segura y utilícelo para verificar la firma en los eventos entregados.

Ejemplo:

"whsec_example_not_a_real_secret"

​
eventTypes
string[]

Los tipos de evento a los que se suscribe este endpoint. Ausente cuando el registro recibe todos los tipos de evento.

Ejemplo:
["transfer.completed"]