Create a Webhook Registration

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" }

Authorizations

Authorization

string

header

required

JWT Bearer token authentication. The tenantId is derived from the bearer token or authenticated request context and is not supplied through X-Organization-Id.

Headers

X-Idempotency

string

required

Required idempotency key for safe retries. Use a UUID v4 or unique business identifier. If the same key is sent again and the original request was already processed, the cached response is returned.

See Retries and idempotency for details.

Maximum string length: 255

Body

application/json

name

string

required

A human-readable name for the registration.

Example:

"Operations webhook"

endpointUrl

string<uri>

required

The endpoint that receives event deliveries. Must be an HTTPS URL.

Pattern: ^https://

Example:

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

enabled

boolean

Whether the registration is active. Defaults to true when omitted.

Example:

true

eventTypes

string[]

The event types this endpoint subscribes to. When omitted, the registration receives every event type. Use the List Webhook Event Types endpoint for the accepted values.

Maximum array length: 64

Example:

["transfer.completed", "transfer.rejected"]

Response

Indicates that the webhook registration was created. The signingSecret is returned only in this response.

Repeated calls with the same X-Idempotency key replay the cached response.

See Retries and idempotency for more details.

string<uuid>

required

The unique identifier of the webhook registration.

Example:

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

name

string

required

The human-readable name of the registration.

Example:

"Operations webhook"

endpointUrl

string<uri>

required

The HTTPS endpoint that receives event deliveries.

Example:

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

enabled

boolean

required

Whether the registration is active.

Example:

true

createdAt

string<date-time>

required

The timestamp when the registration was created.

Example:

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

updatedAt

string<date-time>

required

The timestamp of the last update.

Example:

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

signingSecret

string

required

The server-generated signing secret, returned only in this response. Store it securely and use it to verify the signature on delivered events.

Example:

"whsec_example_not_a_real_secret"

eventTypes

string[]

The event types this endpoint subscribes to. Absent when the registration receives every event type.

Example:

["transfer.completed"]