Create a Webhook Registration

curl --request POST \
  --url https://api.example.com/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"
  ]
}
'

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/webhooks"

	payload := strings.NewReader("{\n  \"name\": \"Operations webhook\",\n  \"endpointUrl\": \"https://hooks.example.com/transfer-events\",\n  \"enabled\": true,\n  \"eventTypes\": [\n    \"transfer.completed\",\n    \"transfer.rejected\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Idempotency", "<x-idempotency>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

const options = {
  method: 'POST',
  headers: {
    'X-Idempotency': '<x-idempotency>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Operations webhook',
    endpointUrl: 'https://hooks.example.com/transfer-events',
    enabled: true,
    eventTypes: ['transfer.completed', 'transfer.rejected']
  })
};

fetch('https://api.example.com/v1/webhooks', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.example.com/v1/webhooks"

payload = {
    "name": "Operations webhook",
    "endpointUrl": "https://hooks.example.com/transfer-events",
    "enabled": True,
    "eventTypes": ["transfer.completed", "transfer.rejected"]
}
headers = {
    "X-Idempotency": "<x-idempotency>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

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

Create a Webhook Registration

Use this endpoint to register a tenant-scoped webhook endpoint that receives transfer event notifications. The registration is scoped to the caller’s tenant, derived from the bearer JWT (tenantId claim), never from a request header.

The server generates the signingSecret and returns it exactly once in this response. Store it securely — it is never returned again. Use it to verify the signature on every delivered event. To obtain a new secret, call the rotate endpoint.

Use the X-Idempotency header for guaranteed deduplication. Repeated calls with the same key replay the cached response.

POST

webhooks

Create a Webhook Registration

curl --request POST \
  --url https://api.example.com/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"
  ]
}
'

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/webhooks"

	payload := strings.NewReader("{\n  \"name\": \"Operations webhook\",\n  \"endpointUrl\": \"https://hooks.example.com/transfer-events\",\n  \"enabled\": true,\n  \"eventTypes\": [\n    \"transfer.completed\",\n    \"transfer.rejected\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Idempotency", "<x-idempotency>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

const options = {
  method: 'POST',
  headers: {
    'X-Idempotency': '<x-idempotency>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Operations webhook',
    endpointUrl: 'https://hooks.example.com/transfer-events',
    enabled: true,
    eventTypes: ['transfer.completed', 'transfer.rejected']
  })
};

fetch('https://api.example.com/v1/webhooks', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.example.com/v1/webhooks"

payload = {
    "name": "Operations webhook",
    "endpointUrl": "https://hooks.example.com/transfer-events",
    "enabled": True,
    "eventTypes": ["transfer.completed", "transfer.rejected"]
}
headers = {
    "X-Idempotency": "<x-idempotency>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

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

Autorizações

Authorization

string

header

obrigatório

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

Cabeçalhos

X-Idempotency

string

obrigatório

Required idempotency key for safe retries. Use a UUID v4 or a unique business identifier, made of letters, digits, ., _, and -. 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

Pattern: ^[a-zA-Z0-9._-]+$

Corpo

application/json

name

string

obrigatório

A human-readable name for the registration.

Exemplo:

"Operations webhook"

endpointUrl

string<uri>

obrigatório

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

Pattern: ^https://

Exemplo:

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

enabled

boolean

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

Exemplo:

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

Exemplo:

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

Resposta

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>

obrigatório

The unique identifier of the webhook registration.

Exemplo:

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

name

string

obrigatório

The human-readable name of the registration.

Exemplo:

"Operations webhook"

endpointUrl

string<uri>

obrigatório

The HTTPS endpoint that receives event deliveries.

Exemplo:

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

enabled

boolean

obrigatório

Whether the registration is active.

Exemplo:

true

createdAt

string<date-time>

obrigatório

The timestamp when the registration was created.

Exemplo:

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

updatedAt

string<date-time>

obrigatório

The timestamp of the last update.

Exemplo:

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

signingSecret

string

obrigatório

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

Exemplo:

"whsec_example_not_a_real_secret"

eventTypes

string[]

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

Exemplo:

["transfer.completed"]

API de Transferências

Painel e API de Conciliação

API de Operações TED In

API de Webhooks

API de Webhook DLQ

Tratamento de erros

Eventos

Create a Webhook Registration

Autorizações

Cabeçalhos

Corpo

Resposta