SocredDocs

    Create Webhook

    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.

    POSThttps://api.socredsa.com.br/v3/accounts/api/webhooks
    curl --request POST \
  --url 'https://api.socredsa.com.br/v3/accounts/api/webhooks' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
  "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"
}'
    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"
}

    Endpoint

    POST /v3/accounts/api/webhooks

    Headers

    ParameterTypeDescriptionExample
    AuthorizationStringBearer + Access_tokenBearer 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"
}
    FieldTypeDescriptionRequired or Optional
    urlStringWebhook URL that will receive the POST notifications. Must start with http:// or https://. The URL will be trimmed of leading/trailing spaces.required
    type_webhookStringType of event that will trigger this webhook. See "Available Webhook Types" section below for all options.required
    authorization_tokenStringCustom authorization token to be sent in the webhook request header. Maximum 255 characters. Use this for Bearer tokens or custom authentication.optional
    x_functions_keyStringAzure Functions key or similar authentication key to be sent in the webhook request header. Maximum 255 characters.optional
    source_account_branch_identifierStringBranch identifier (agency number) of the account that will be associated with this webhook.required
    source_account_numberStringAccount number of the account that will be associated with this webhook.required

    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"
}
    FieldDescription
    idUnique webhook identifier generated. This value never repeats and can be used to update or delete the webhook.
    urlThe webhook URL (normalized and trimmed)
    type_webhookThe type of event configured for this webhook
    authorization_tokenThe authorization token configured (if provided)
    x_functions_keyThe Azure Functions key configured (if provided)
    created_atTimestamp when the webhook was created
    updated_atTimestamp when the webhook was last updated

    Error Responses

    HTTP CodeError MessageDescription
    400Invalid URL format. Must start with http:// or https://The URL provided is not in a valid format. Ensure it starts with http:// or https://.
    400Account not foundThe specified account was not found or you do not have access to it.
    400Account is closedThe specified account is closed. Webhooks cannot be created for closed accounts.
    400Webhook with the same URL, type and account already existsA webhook with the exact same URL, type, and account combination already exists. Each combination must be unique.
    400Maximum limit of 3 webhooks of type 'XXX' reached for account ID YYYYou have reached the maximum limit of 3 webhooks per type for this account. Delete an existing webhook before creating a new one.
    401UnauthorizedInvalid or missing authentication token. Ensure you are sending a valid Bearer token.
    422Validation errorOne 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_token and x_functions_key are 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