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 mirror accounts.
Headers
| Parameter | Type | Description | Example |
|---|---|---|---|
| Authorization | String | Bearer + Access_token | Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNzEzMzAwOTMxLCJpYXQiOjE3MTMyOTczMzEsImp0aSI6Ijc2ZWI4ZTE5ZjM4YjQ4NmZiODdmNzNjNTdkMWVmNDJhIiwidXNlcl9pZCI6MjQ2fQ.5zekMa7CUj9p-MvNHns5ke4ZPhYV3Y1CLOsYL7hDUUo |
| hmac | String | HMAC (Hash-based Message Authentication Code) is an authentication algorithm that combines a private key with a message to create a Message Authentication Code (MAC). | hmac: 57373705c83bc5efe41001790c54642e670088c0c87d56bc8f990f2260c7740b99f4081ff231b87f82118c1e77a959e1f40eacf690a8fa61a827a9ba01d546f6 |
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 mirror account that will be associated with this webhook. | required |
| source_account_number | String | Account number of the mirror 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 | Company not found | The authenticated company was not found in the system. Verify your authentication token. |
| 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 mirror account was not found, does not belong to your company, or your user does not have permission to access it. |
| 400 | Account is closed | The specified mirror 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 number YYY | You have reached the maximum limit of 3 webhooks per type for this account. Delete an existing webhook before creating a new one. |
| 422 | Validation error | One or more required fields are missing or invalid. Check the error details in the response body. |
Business Rules
Validations:
- Account must exist and belong to the authenticated
- User must have an active policy for the specified account (returns
400 Account not foundif not) - Account cannot be closed
- URL must be in valid format (http:// or https://)
- URL cannot be empty after trimming spaces
- Maximum of 3 webhooks per type per account
Webhook Limits:
- Each account can have up to 3 webhooks of the same type
- 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 Considerations:
- 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