SocredDocs

    Update Webhook

    This API allows you to update an existing webhook configuration. You can modify the URL, webhook type, or authentication tokens. The account association cannot be changed - to associate a webhook with a different account, you must delete and recreate it.

    PATCHhttps://api.socredsa.com.br/v3/accounts/api/webhooks/{webhook_id}
    curl --request PATCH \
  --url 'https://api.socredsa.com.br/v3/accounts/api/webhooks/{webhook_id}' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
  "url": "https://your-domain.com/new-webhook-endpoint",
  "type_webhook": "CASHIN",
  "authorization_token": "Bearer new-token-here",
  "x_functions_key": "new-azure-function-key"
}'
    Response200
    {
  "id": 789,
  "url": "https://your-domain.com/new-webhook-endpoint",
  "type_webhook": "CASHIN",
  "authorization_token": "Bearer new-token-here",
  "x_functions_key": "new-azure-function-key",
  "created_at": "2026-04-18T10:30:00Z",
  "updated_at": "2026-04-18T15:45:00Z"
}

    Endpoint

    PATCH /v3/accounts/api/webhooks/{webhook_id}

    Headers

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

    Path Parameters

    ParameterTypeDescriptionExample
    webhook_idIntegerThe ID of the webhook to update. This is the ID returned when the webhook was created.789

    Body Details

    All body fields are optional. Only include the fields you want to update. Account association cannot be changed — to move a webhook to a different account, delete it and create a new one.

    {
  "url": "https://your-domain.com/new-webhook-endpoint",
  "type_webhook": "CASHIN",
  "authorization_token": "Bearer new-token-here",
  "x_functions_key": "new-azure-function-key"
}
    FieldTypeDescriptionRequired or Optional
    urlStringNew webhook URL. Must start with http:// or https://. The URL will be trimmed of leading/trailing spaces.optional
    type_webhookStringNew webhook type. See "Available Webhook Types" section below for all options.optional
    authorization_tokenStringNew authorization token. Maximum 255 characters. Set to null or omit to remove.optional
    x_functions_keyStringNew Azure Functions key. Maximum 255 characters. Set to null or omit to remove.optional

    Request Examples

    Update only the URL:

    {
  "url": "https://new-domain.com/webhook"
}

    Update webhook type and tokens:

    {
  "type_webhook": "ALL",
  "authorization_token": "Bearer updated-token",
  "x_functions_key": "updated-key"
}

    Remove authentication tokens:

    {
  "authorization_token": null,
  "x_functions_key": null
}

    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/new-webhook-endpoint",
  "type_webhook": "CASHIN",
  "authorization_token": "Bearer new-token-here",
  "x_functions_key": "new-azure-function-key",
  "created_at": "2026-04-18T10:30:00Z",
  "updated_at": "2026-04-18T15:45:00Z"
}
    FieldDescription
    idUnique webhook identifier (unchanged)
    urlThe updated webhook URL (or original if not changed)
    type_webhookThe updated webhook type (or original if not changed)
    authorization_tokenThe updated authorization token (or original if not changed, null if removed)
    x_functions_keyThe updated Azure Functions key (or original if not changed, null if removed)
    created_atOriginal creation timestamp (unchanged)
    updated_atTimestamp when the webhook was last updated (reflects the current update)

    Error Responses

    HTTP CodeError MessageDescription
    400Account is closedThe webhook's associated account is closed. Webhooks for closed accounts cannot be updated.
    400Webhook with the same URL, type and account already existsAnother webhook with this URL and type combination already exists for this account. Each combination must be unique.
    401UnauthorizedInvalid or missing authentication token. Ensure you are sending a valid Bearer token.
    404Webhook not foundThe webhook with the specified ID was not found or you do not have access to it.
    422Validation errorOne or more fields have invalid values. Check the error details in the response body.

    Business Rules

    Authentication:

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

    Validations:

    • Webhook must exist and be accessible by the authenticated user
    • Account cannot be closed
    • URL must be in valid format if provided (http:// or https://)
    • URL cannot be empty after trimming spaces
    • New URL + type combination must be unique for the account (excludes the current webhook itself)

    Update Behavior:

    • Only fields included in the request body are updated
    • Fields not included remain unchanged
    • Setting a field to null removes its value
    • The updated_at timestamp is automatically updated

    Account Immutability:

    • The webhook's account association cannot be changed
    • To move a webhook to a different account, delete it and create a new one