post
https://api.somossimpay.com.br/v3/accounts/api/webhooks
This API allows you to register a new webhook to receive real-time notifications about transactions and events in your account. You can configure webhooks for different types of events and associate them with specific accounts.
Recent Requests
Log in to see full request history
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Loading…
Endpoint
POST /v3/accounts/api/webhooksHeaders
| Parameter | Type | Description | Example |
|---|---|---|---|
| Authorization | String | Bearer + Access_token | Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNzEzMzAwOTMxLCJpYXQiOjE3MTMyOTczMzEsImp0aSI6Ijc2ZWI4ZTE5ZjM4YjQ4NmZiODdmNzNjNTdkMWVmNDJhIiwidXNlcl9pZCI6MjQ2fQ.5zekMa7CUj9p-MvNHns5ke4ZPhYV3Y1CLOsYL7hDUUo |
Body Details
{
"url": "https://your-domain.com/webhook/endpoint",
"type_webhook": "PIX_CASHOUT_SUCCESS",
"authorization_token": "Bearer your-custom-token-here",
"x_functions_key": "your-azure-function-key",
"source_account_branch_identifier": "0001",
"source_account_number": "123456"
}| Field | Type | Description | Required or Optional |
|---|---|---|---|
| url | String | Webhook URL that will receive the POST notifications. Must start with http:// or https://. The URL will be trimmed of leading/trailing spaces. | required |
| type_webhook | String | Type of event that will trigger this webhook. See "Available Webhook Types" section below for all options. | required |
| authorization_token | String | Custom authorization token to be sent in the webhook request header. Maximum 255 characters. Use this for Bearer tokens or custom authentication. | optional |
| x_functions_key | String | Azure Functions key or similar authentication key to be sent in the webhook request header. Maximum 255 characters. | optional |
| source_account_branch_identifier | String | Branch identifier (agency number) of the account that will be associated with this webhook. | required |
| source_account_number | String | Account number of the account that will be associated with this webhook. | required |
Available Webhook Types
| Type | Description |
|---|---|
| ALL | Receives notifications for all transaction types |
| INTERNAL | Receives notifications for internal transactions (transfers between accounts in the same institution) |
| INTERNAL APPROVE | Receives notifications when internal transactions are approved |
| INTEGRATION | Receives notifications for integration events |
| CASHIN | Receives notifications for all cash-in transactions (money entering the account) |
| CASHOUT | Receives notifications for all cash-out transactions (money leaving the account) |
| PIX_CASHOUT_CREATED | Receives notifications when a PIX cashout is created |
| PIX_CASHOUT_SUCCESS | Receives notifications when a PIX cashout is successfully completed |
Response Details
{
"id": 789,
"url": "https://your-domain.com/webhook/endpoint",
"type_webhook": "PIX_CASHOUT_SUCCESS",
"authorization_token": "Bearer your-custom-token-here",
"x_functions_key": "your-azure-function-key",
"created_at": "2026-04-18T10:30:00Z",
"updated_at": "2026-04-18T10:30:00Z"
}| Field | Description |
|---|---|
| id | Unique webhook identifier generated. This value never repeats and can be used to update or delete the webhook. |
| url | The webhook URL (normalized and trimmed) |
| type_webhook | The type of event configured for this webhook |
| authorization_token | The authorization token configured (if provided) |
| x_functions_key | The Azure Functions key configured (if provided) |
| created_at | Timestamp when the webhook was created |
| updated_at | Timestamp when the webhook was last updated |
Error Responses
| HTTP Code | Error Message | Description |
|---|---|---|
| 400 | Invalid URL format. Must start with http:// or https:// | The URL provided is not in a valid format. Ensure it starts with http:// or https://. |
| 400 | Account not found | The specified account was not found or you do not have access to it. |
| 400 | Account is closed | The specified account is closed. Webhooks cannot be created for closed accounts. |
| 400 | Webhook with the same URL, type and account already exists | A webhook with the exact same URL, type, and account combination already exists. Each combination must be unique. |
| 400 | Maximum limit of 3 webhooks of type 'XXX' reached for account ID YYY | You have reached the maximum limit of 3 webhooks per type for this account. Delete an existing webhook before creating a new one. |
| 401 | Unauthorized | Invalid or missing authentication token. Ensure you are sending a valid Bearer token. |
| 422 | Validation error | One or more required fields are missing or invalid. Check the error details in the response body. |
Business Rules
Authentication:
- Requires valid authentication token
- User must be authenticated and have access to the specified account
Validations:
- Account must exist and be accessible by the authenticated user
- Account cannot be closed
- URL must be in valid format (http:// or https://)
- URL cannot be empty after trimming spaces
- Each combination of URL, type, and account must be unique
Webhook Limits:
- Maximum of 3 webhooks per type per account
- Different types can coexist (e.g., 3 PIX_CASHOUT_SUCCESS + 3 PIX_CASHOUT_CREATED)
- No limit on the total number of webhooks per account (only per type)
Security:
- Both
authorization_tokenandx_functions_keyare optional but recommended for securing your webhook endpoint - These values will be sent in the headers when your webhook is triggered
- Store sensitive tokens securely and rotate them periodically
Bad request - Invalid parameters
Unauthorized - Invalid or missing authentication
Internal server error