SimPayDocs

    List 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.

    GEThttps://api.somossimpay.com.br/v3/accounts/api/webhooks
    curl --request GET \
  --url 'https://api.somossimpay.com.br/v3/accounts/api/webhooks' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>'
    Response200
    [
  {
    "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"
  }
]

    Endpoint

    GET /v3/accounts/api/webhooks

    Headers

    ParameterTypeDescriptionExample
    AuthorizationStringBearer + Access_tokenBearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNzEzMzAwOTMxLCJpYXQiOjE3MTMyOTczMzEsImp0aSI6Ijc2ZWI4ZTE5ZjM4YjQ4NmZiODdmNzNjNTdkMWVmNDJhIiwidXNlcl9pZCI6MjQ2fQ.5zekMa7CUj9p-MvNHns5ke4ZPhYV3Y1CLOsYL7hDUUo

    Query Parameters

    source_account_branch_identifier and source_account_number are required. The remaining parameters are optional filters.

    ParameterTypeDescriptionRequired or OptionalExample
    source_account_branch_identifierStringBranch identifier (agency number) of the account to list webhooks for.required0001
    source_account_numberStringAccount number of the account to list webhooks for.required123456
    webhook_idIntegerFilter by specific webhook ID. Returns only the webhook with this ID.optional789
    type_webhookStringFilter by webhook type. Returns all webhooks of this type. See "Available Webhook Types" section for valid values.optionalPIX_CASHOUT_SUCCESS

    Request Examples

    Get all webhooks for a specific account:

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

    Get a specific webhook by ID:

    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:

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

    Combine all filters:

    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

    TypeDescription
    ALLReceives notifications for all transaction types
    INTERNALReceives notifications for internal transactions (transfers between accounts in the same institution)
    INTERNAL APPROVEReceives notifications when internal transactions are approved
    INTEGRATIONReceives notifications for integration events
    CASHINReceives notifications for all cash-in transactions (money entering the account)
    CASHOUTReceives notifications for all cash-out transactions (money leaving the account)
    PIX_CASHOUT_CREATEDReceives notifications when a PIX cashout is created
    PIX_CASHOUT_SUCCESSReceives 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"
  }
]
    FieldDescription
    idUnique webhook identifier. Use this ID to update or delete the webhook.
    urlThe webhook URL that receives the POST notifications
    type_webhookThe type of event configured for this webhook
    authorization_tokenThe authorization token configured (null if not set)
    x_functions_keyThe Azure Functions key configured (null if not set)
    created_atTimestamp when the webhook was created
    updated_atTimestamp 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 CodeError MessageDescription
    400Account not foundThe specified account was not found or you do not have access to it.
    400Account is closedThe specified account is closed. Cannot retrieve webhooks for closed accounts.
    401UnauthorizedInvalid or missing authentication token. Ensure you are sending a valid Bearer token.
    422Validation errorRequired 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)