> ## Documentation Index > Fetch the complete documentation index at: https://docs.vitawallet.io/llms.txt > Use this file to discover all available pages before exploring further. # Update Webhook Configuration > Updates the webhook configuration for your business, setting or replacing the destination URL and the list of subscribed categories. #### Before Vita Accepts the New URL: Pre-Verification Ping As soon as you submit a new `webhook_url`, Vita immediately sends an **unsigned** test request to that URL: ```json {"test":true,"timestamp":"..."} ``` Your server must respond with a `2xx` or `3xx` status code **within 10 seconds**, or the configuration update is rejected. This request carries **no signature** — if your server is built to reject unsigned requests (as recommended for regular webhooks), it will also reject this pre-verification ping and you will never be able to save a new URL. Make sure your endpoint accepts this specific unsigned probe, or temporarily relax validation while configuring. #### Post-Update Test Webhook (Conditional) After a successful update, Vita attempts to send a **signed** test webhook using the most recent transaction that matches your configured categories. This only happens if such a transaction exists: - **If a matching transaction exists:** the response message is `"Webhook configuration updated successfully. You will receive a test webhook in the next few minutes."`, and the test webhook is sent shortly after. - **If no matching transaction exists** (e.g., new business, or categories with no history): the response message is instead `"Webhook configuration updated successfully. However, no transaction was found matching the configured categories to send a test webhook. You will receive webhooks when new transactions occur matching the configured categories."` — and no test webhook is sent at all. Both outcomes save the configuration correctly; only the test-webhook behavior differs. #### Request Body | Field | Type | Description | | --- | --- | --- | | `webhook_url` | string (required) | HTTPS URL where webhook notifications will be sent. | | `categories` | string[\] (Required (see note)) | List of transaction categories to subscribe to. Must contain valid categories returned by Get Webhook Configuration (`available_categories`). | > **`categories`** **is documented as required, but the API currently accepts the request without it — and interprets a missing** **`categories`** **field as "unsubscribe from everything."** Until this is enforced API-side, always send the field explicitly with your full intended list to avoid silently losing all your subscriptions. > **There is currently no way to remove your webhook configuration by sending** **`webhook_url: null`** **or an empty string.** Both are rejected by the API with a `422` error (`"URL is blank"`), and the existing configuration is left unchanged. If you need to stop receiving webhooks, contact your integration contact — self-service removal is not available today. #### Request Example ```bash curl --location --request PUT 'https://api.vitawallet.io/api/businesses/webhooks' \ --header 'X-Login: {your_x_login}' \ --header 'X-Trans-Key: {your_x_trans_key}' \ --header 'X-Date: {current_iso8601_timestamp_with_timezone}' \ --header 'Authorization: {signature_calculated_per_the_Business_API_authentication_doc}' \ --header 'Content-Type: application/json' \ --data '{ "webhook_url": "https://myserver.com/webhook", "categories": [ "transfer", "deposit" ] }' ``` #### Response Example ```json { "message": "Webhook configuration updated successfully. You will receive a test webhook in the next few minutes.", "webhook_url": "https://myserver.com/webhook", "categories": [ "transfer", "deposit" ] } ``` #### Important Considerations **Use HTTPS** The webhook URL must use HTTPS. HTTP URLs are not accepted for security reasons. **Your Server Must Handle Two Kinds of Incoming Test Traffic** 1. The unsigned pre-verification ping described above, sent the moment you submit a new URL. 2. The signed post-update test webhook, sent only when a matching transaction exists. **Replace, Not Append** The `categories` array completely replaces the existing list. Always send the full list of categories you want active — and always include the field, since omitting it clears all subscriptions. **Removing the Webhook** Self-service removal via `null`/empty string is not currently supported. Contact your integration contact if you need your configuration removed. ## OpenAPI ````yaml /openapi.yaml put /api/businesses/webhooks openapi: 3.0.0 info: title: Vita Business API description: >- Vita Wallet Business API — integra payins, payouts, exchange, transactions, users y webhooks para operar pagos en LatAm y el mundo. version: 1.0.0 contact: name: Vita Wallet Support url: https://vitawallet.io email: empresas@vitawallet.io servers: - url: https://api.vitawallet.io description: Production - url: https://api.stage.vitawallet.io description: Sandbox security: - xLogin: [] xTransKey: [] xDate: [] hmacSignature: [] tags: - name: Create Payin - name: Direct Payment - name: Exchange - name: Vita Sent - name: Bank Payouts - name: External Crypto Payouts - name: Transactions - name: Users Creation - name: User Information - name: Webhooks externalDocs: url: https://vitawallet.io description: Vita Wallet paths: /api/businesses/webhooks: put: tags: - Webhooks summary: Update Webhook Configuration description: >- Updates the webhook configuration for your business, setting or replacing the destination URL and the list of subscribed categories. #### Before Vita Accepts the New URL: Pre-Verification Ping As soon as you submit a new `webhook_url`, Vita immediately sends an **unsigned** test request to that URL: ```json {"test":true,"timestamp":"..."} ``` Your server must respond with a `2xx` or `3xx` status code **within 10 seconds**, or the configuration update is rejected. This request carries **no signature** — if your server is built to reject unsigned requests (as recommended for regular webhooks), it will also reject this pre-verification ping and you will never be able to save a new URL. Make sure your endpoint accepts this specific unsigned probe, or temporarily relax validation while configuring. #### Post-Update Test Webhook (Conditional) After a successful update, Vita attempts to send a **signed** test webhook using the most recent transaction that matches your configured categories. This only happens if such a transaction exists: - **If a matching transaction exists:** the response message is `"Webhook configuration updated successfully. You will receive a test webhook in the next few minutes."`, and the test webhook is sent shortly after. - **If no matching transaction exists** (e.g., new business, or categories with no history): the response message is instead `"Webhook configuration updated successfully. However, no transaction was found matching the configured categories to send a test webhook. You will receive webhooks when new transactions occur matching the configured categories."` — and no test webhook is sent at all. Both outcomes save the configuration correctly; only the test-webhook behavior differs. #### Request Body | Field | Type | Description | | --- | --- | --- | | `webhook_url` | string (required) | HTTPS URL where webhook notifications will be sent. | | `categories` | string[\] (Required (see note)) | List of transaction categories to subscribe to. Must contain valid categories returned by Get Webhook Configuration (`available_categories`). | > **`categories`** **is documented as required, but the API currently accepts the request without it — and interprets a missing** **`categories`** **field as "unsubscribe from everything."** Until this is enforced API-side, always send the field explicitly with your full intended list to avoid silently losing all your subscriptions. > **There is currently no way to remove your webhook configuration by sending** **`webhook_url: null`** **or an empty string.** Both are rejected by the API with a `422` error (`"URL is blank"`), and the existing configuration is left unchanged. If you need to stop receiving webhooks, contact your integration contact — self-service removal is not available today. #### Request Example ```bash curl --location --request PUT 'https://api.vitawallet.io/api/businesses/webhooks' \ --header 'X-Login: {your_x_login}' \ --header 'X-Trans-Key: {your_x_trans_key}' \ --header 'X-Date: {current_iso8601_timestamp_with_timezone}' \ --header 'Authorization: {signature_calculated_per_the_Business_API_authentication_doc}' \ --header 'Content-Type: application/json' \ --data '{ "webhook_url": "https://myserver.com/webhook", "categories": [ "transfer", "deposit" ] }' ``` #### Response Example ```json { "message": "Webhook configuration updated successfully. You will receive a test webhook in the next few minutes.", "webhook_url": "https://myserver.com/webhook", "categories": [ "transfer", "deposit" ] } ``` #### Important Considerations **Use HTTPS** The webhook URL must use HTTPS. HTTP URLs are not accepted for security reasons. **Your Server Must Handle Two Kinds of Incoming Test Traffic** 1. The unsigned pre-verification ping described above, sent the moment you submit a new URL. 2. The signed post-update test webhook, sent only when a matching transaction exists. **Replace, Not Append** The `categories` array completely replaces the existing list. Always send the full list of categories you want active — and always include the field, since omitting it clears all subscriptions. **Removing the Webhook** Self-service removal via `null`/empty string is not currently supported. Contact your integration contact if you need your configuration removed. operationId: update-webhook-configuration requestBody: content: application/json: schema: type: object example: webhook_url: https://myserver.com categories: - deposit responses: '200': description: Successful response. content: application/json: examples: SuccessUpdateWebhookConfiguration: summary: Success - Update webhook configuration value: message: >- Webhook configuration updated successfully. You will receive a test webhook in the next few minutes. webhook_url: https://myserver.com/webhook categories: - transfer - deposit FailIsNotCategory: summary: Fail - Is not category value: error: code: 500 message: >- Invalid categories: is_not_exist. Valid categories are: sent, received, deposit, withdrawal, exchange, fee, payment, transfer, vita_card, tax, cash_back_coupon, service_payment, adjustment, card_credit_adjustment, card_debit_adjustment, card_transaction, request_charge, card_maintenance, microdeposit FailWebhookUrlIsNotValid: summary: Fail - Webhook url is not valid value: error: code: 500 message: URL must use HTTPS protocol SuccessTransactionNotFound: summary: Success - Transaction not found value: message: >- Webhook configuration updated successfully. However, no transaction was found matching the configured categories to send a test webhook. You will receive webhooks when new transactions occur matching the configured categories. webhook_url: https://myserver.com/webhook categories: - microdeposit FaildWebhookUrlInactive: summary: Faild - Webhook Url Inactive value: error: code: 400 message: >- Webhook URL returned invalid status: HTTP 500. Server must respond with a valid HTTP status (2xx or 3xx). components: securitySchemes: xLogin: type: apiKey in: header name: x-login description: Business xLogin xTransKey: type: apiKey in: header name: x-trans-key description: Business xTransKey xDate: type: apiKey in: header name: x-date description: ISO8601 datetime hmacSignature: type: apiKey in: header name: Authorization description: 'V2-HMAC-SHA256 signature. Example: `V2-HMAC-SHA256, Signature: `' ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.