Update Webhook

PATCH https://api.somossimpay.com.br/v3/accounts/api/webhooks/{webhook_id}

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.

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

Path Parameters

Parameter	Type	Description	Example
webhook_id	Integer	The 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.

Body JSON (Raw)

{
  "url": "https://your-domain.com/new-webhook-endpoint",
  "type_webhook": "CASHIN",
  "authorization_token": "Bearer new-token-here",
  "x_functions_key": "new-azure-function-key"
}

Field	Type	Description	Required or Optional
url	String	New webhook URL. Must start with http:// or https://. The URL will be trimmed of leading/trailing spaces.	optional
type_webhook	String	New webhook type. See "Available Webhook Types" section below for all options.	optional
authorization_token	String	New authorization token. Maximum 255 characters. Set to null or omit to remove.	optional
x_functions_key	String	New Azure Functions key. Maximum 255 characters. Set to null or omit to remove.	optional

Request Examples

Update only the URL:

JSON

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

Update webhook type and tokens:

JSON

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

Remove authentication tokens:

JSON

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

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/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"
}

Field	Description
id	Unique webhook identifier (unchanged)
url	The updated webhook URL (or original if not changed)
type_webhook	The updated webhook type (or original if not changed)
authorization_token	The updated authorization token (or original if not changed, null if removed)
x_functions_key	The updated Azure Functions key (or original if not changed, null if removed)
created_at	Original creation timestamp (unchanged)
updated_at	Timestamp when the webhook was last updated (reflects the current update)

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 is closed	The webhook's associated mirror account is closed. Webhooks for closed accounts cannot be updated.
400	Webhook with the same URL, type and account already exists	Another webhook with this URL and type combination already exists for this account. Each combination must be unique.
404	Webhook not found	The webhook with the specified ID was not found, does not belong to your company, or your user does not have an active policy for the associated account.
422	Validation error	One or more fields have invalid values. Check the error details in the response body.

Business Rules

Validations:

• Webhook must exist and belong to the authenticated company
• User must have an active policy for the webhook's associated mirror account (returns 404 Webhook not found if not)
• Mirror 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

Duplicate Prevention:

• When updating URL or type, the system checks if the new combination already exists
• The check excludes the current webhook being updated
• This prevents accidental duplicates while allowing you to update other fields

Account Immutability:

• The webhook's account association cannot be changed
• If you need to move a webhook to a different account:
  1. Delete the webhook from the current account
  2. Create a new webhook on the target account