get
https://api.somossimpay.com.br/v3/accounts/webhooks
This API allows you to retrieve a list of registered webhooks for your company. You can filter by webhook ID, type, or specific mirror account to narrow down the results.
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 |
Query Parameters
source_account_branch_identifier and source_account_number are required. The remaining parameters are optional filters.
| Parameter | Type | Description | Required or Optional | Example |
|---|---|---|---|---|
| source_account_branch_identifier | String | Branch identifier (agency number) of the mirror account to list webhooks for. | required | 0001 |
| source_account_number | String | Account number of the mirror account to list webhooks for. | required | 123456 |
| webhook_id | Integer | Filter by specific webhook ID. Returns only the webhook with this ID. | optional | 789 |
| type_webhook | String | Filter by webhook type. Returns all webhooks of this type. See "Available Webhook Types" section for valid values. | optional | PIX_CASHOUT_SUCCESS |
Request Examples
Get all webhooks for a specific account:
GET /api/webhooks?source_account_branch_identifier=0001&source_account_number=123456
Get a specific webhook by ID:
GET /api/webhooks?source_account_branch_identifier=0001&source_account_number=123456&webhook_id=789
Filter by webhook type for a specific account:
GET /api/webhooks?source_account_branch_identifier=0001&source_account_number=123456&type_webhook=PIX_CASHOUT_SUCCESS
Combine all filters:
GET /api/webhooks?source_account_branch_identifier=0001&source_account_number=123456&type_webhook=CASHIN&webhook_id=789
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"
},
{
"id": 790,
"url": "https://your-domain.com/webhook/cashin",
"type_webhook": "CASHIN",
"authorization_token": null,
"x_functions_key": null,
"created_at": "2026-04-17T14:20:00Z",
"updated_at": "2026-04-17T14:20:00Z"
}
]
| Field | Description |
|---|---|
| id | Unique webhook identifier. Use this ID to update or delete the webhook. |
| url | The webhook URL that receives the POST notifications |
| type_webhook | The type of event configured for this webhook |
| authorization_token | The authorization token configured (null if not set) |
| x_functions_key | The Azure Functions key configured (null if not set) |
| created_at | Timestamp when the webhook was created |
| updated_at | Timestamp when the webhook was last updated |
Note: The response is always an array, even if filtering by webhook_id returns a single result or no results.
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 | Account not found | The specified mirror account was not found, does not belong to your company, or your user does not have an active policy for it. |
| 400 | Account is closed | The specified mirror account is closed. Cannot retrieve webhooks for closed accounts. |
| 422 | Validation error | Required query parameters are missing or invalid. |
Business Rules
Filtering Behavior:
source_account_branch_identifierandsource_account_numberare mandatory — the list is always scoped to a specific account- Account only: Returns all webhooks for the account
- + webhook_id: Also filters by the specific webhook ID
- + type_webhook: Also filters by webhook type
- Multiple optional filters combine with AND logic
Account Validation:
- When filtering by account, the system validates:
- User has permission to access the account
- Account exists and belongs to the company
- Account is not closed
Response Characteristics:
- Empty array
[]is returned when no webhooks match the filters - Results are not paginated (returns all matching webhooks)
- Webhooks are returned in the order they were created (oldest first)