List Webhooks

GET https://api.somossimpay.com.br/v3/accounts/api/webhooks

This API allows you to retrieve a list of registered webhooks for your account. You can filter by webhook ID, type, or specific account to narrow down the results.

Endpoint

GET /v3/accounts/api/webhooks

Headers

Parameter	Type	Description	Example
Authorization	String	Bearer + Access_token	Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNzEzMzAwOTMxLCJpYXQiOjE3MTMyOTczMzEsImp0aSI6Ijc2ZWI4ZTE5ZjM4YjQ4NmZiODdmNzNjNTdkMWVmNDJhIiwidXNlcl9pZCI6MjQ2fQ.5zekMa7CUj9p-MvNHns5ke4ZPhYV3Y1CLOsYL7hDUUo

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 account to list webhooks for.	required	0001
source_account_number	String	Account number of the 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:

HTTP

GET /v3/webhooks?source_account_branch_identifier=0001&source_account_number=123456
Authorization: Bearer <access_token>

Get a specific webhook by ID:

HTTP

GET /v3/webhooks?source_account_branch_identifier=0001&source_account_number=123456&webhook_id=789
Authorization: Bearer <access_token>

Filter by webhook type for a specific account:

HTTP

GET /v3/webhooks?source_account_branch_identifier=0001&source_account_number=123456&type_webhook=PIX_CASHOUT_SUCCESS
Authorization: Bearer <access_token>

Combine all filters:

HTTP

GET /v3/webhooks?source_account_branch_identifier=0001&source_account_number=123456&type_webhook=CASHIN&webhook_id=789
Authorization: Bearer <access_token>

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

Response

[
  {
    "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	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. Cannot retrieve webhooks for closed accounts.
401	Unauthorized	Invalid or missing authentication token. Ensure you are sending a valid Bearer token.
422	Validation error	Required query parameters are missing or invalid.

Business Rules

Authentication:

• Requires valid authentication token
• User must be authenticated and have access to the specified account

Filtering:

• source_account_branch_identifier and source_account_number are mandatory — the list is always scoped to a specific account
• Additional filters combine with AND logic:
  • Account only: Returns all webhooks for the account
  • + webhook_id: Also filters by the specific webhook ID
  • + type_webhook: Also filters by webhook type

Validations:

• User must have access to the specified account
• Account must exist
• Account cannot be closed

Response:

• 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)