> For the complete documentation index, see [llms.txt](https://docs.qentaz.com/documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.qentaz.com/documentation/webhooks/configurar-webhook.md).

# Configurar webhook

Este endpoint permite configurar la URL del webhook, un encabezado personalizado y los eventos habilitados para tu negocio o para una cuenta administrada. La configuración se aplica a una cuenta por solicitud.

## Ruta

<mark style="color:green;">`PATCH`</mark> `/v1/business/webhook`

## **Encabezado**

| Name                                                   | Value                                    |
| ------------------------------------------------------ | ---------------------------------------- |
| `Content-Type`*<mark style="color:red;">**\***</mark>* | application/json                         |
| `x-auth-token`*<mark style="color:red;">**\***</mark>* | {token}                                  |
| `child-id`                                             | Identificador de la cuenta administrada. |

Para configurar una cuenta administrada, envía su `business_id` en `child-id`. La API valida que el negocio asociado al token administre esa cuenta. Para configurar tu propio negocio, omite `child-id`.

La credencial debe tener permiso `PATCH` para `/v1/business/webhook`. Las credenciales de tipo `system` conservan su excepción general de permisos.

## **Cuerpo**

| Name                  | Type          | Description                                                                |
| --------------------- | ------------- | -------------------------------------------------------------------------- |
| `webhook_url`         | string o null | URL HTTP o HTTPS que recibirá los eventos. Envía `null` para eliminarla.   |
| `custom_header`       | object o null | Encabezado personalizado. Envía `null` para eliminarlo.                    |
| `custom_header.key`   | string        | Nombre del encabezado. Requerido al enviar el objeto.                      |
| `custom_header.value` | string        | Valor del encabezado. Requerido al enviar el objeto.                       |
| `webhook_events`      | object        | Eventos a habilitar (`true`) o deshabilitar (`false`), agrupados por tipo. |

Envía al menos uno de estos campos: `webhook_url`, `custom_header` o `webhook_events`. Los campos y eventos omitidos conservan su valor. Los eventos requieren booleanos JSON (`true` o `false`); no se aceptan cadenas ni nombres desconocidos. Si la validación falla, la solicitud completa responde 400 y no se aplica ningún cambio.

{% hint style="info" %}
El valor del encabezado se almacena cifrado y no se devuelve ni se registra en las respuestas o logs de este endpoint.
{% endhint %}

El nombre del encabezado debe ser válido para HTTP y no puede contener `||`. No se admiten `Host`, `Content-Type`, `Content-Length`, `Transfer-Encoding` ni nombres que empiecen por `X-Trazo-`. Evita usar `Authorization` si necesitas conservar el encabezado que Trazo envía por defecto.

## **Respuesta**

{% tabs %}
{% tab title="200" %}

```json
{
  "business_id": "PAY-CHILD-001",
  "updated_fields": [
    "business_webhook",
    "business_webhook_header"
  ]
}
```

{% endtab %}

{% tab title="400" %}

```json
{
  "error": "Solicitud inválida: revisa webhook_url, custom_header y webhook_events"
}
```

{% endtab %}

{% tab title="401" %}
El token está ausente o no es válido.
{% endtab %}

{% tab title="403" %}
La credencial no tiene permiso para el endpoint o no administra la cuenta solicitada.
{% endtab %}

{% tab title="404" %}
No se encontró el negocio seleccionado.
{% endtab %}

{% tab title="500" %}
No fue posible guardar la configuración.
{% endtab %}
{% endtabs %}

***

## Ejemplo

Los ejemplos configuran una cuenta administrada. Para configurar el negocio del token, omite el encabezado `child-id`.

{% tabs %}
{% tab title="cURL" %}

```bash
curl --location --request PATCH '{{base_url}}/v1/business/webhook' \
--header 'x-auth-token: YOUR_TOKEN' \
--header 'child-id: PAY-CHILD-001' \
--header 'Content-Type: application/json' \
--data '{
  "webhook_url": "https://ejemplo.com/webhook",
  "custom_header": {
    "key": "test-token",
    "value": "YOUR_SECRET_VALUE"
  }
}'
```

{% endtab %}

{% tab title="NodeJS (Axios)" %}

```javascript
const axios = require("axios");

const data = {
  webhook_url: "https://ejemplo.com/webhook",
  custom_header: {
    key: "test-token",
    value: "YOUR_SECRET_VALUE"
  }
};

axios.patch(`${base_url}/v1/business/webhook`, data, {
  headers: {
    "x-auth-token": token,
    "child-id": "PAY-CHILD-001",
    "Content-Type": "application/json"
  }
})
.then(response => console.log(response.data))
.catch(error => console.log(error.response?.data));
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = f"{base_url}/v1/business/webhook"
payload = {
    "webhook_url": "https://ejemplo.com/webhook",
    "custom_header": {
        "key": "test-token",
        "value": "YOUR_SECRET_VALUE"
    }
}
headers = {
    "x-auth-token": token,
    "child-id": "PAY-CHILD-001",
    "Content-Type": "application/json"
}

response = requests.patch(url, headers=headers, json=payload)
print(response.json())
```

{% endtab %}
{% endtabs %}

### Actualización parcial

Para eliminar solo el encabezado personalizado, conserva la URL y envía:

```json
{
  "custom_header": null
}
```

### Configurar eventos

En `webhook_events`, envía solo los eventos que deseas cambiar. Por ejemplo, esta solicitud activa `payment.success` y desactiva `payout.failed` sin modificar los demás:

```bash
curl --request PATCH '{{base_url}}/v1/business/webhook' \
  --header 'x-auth-token: YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "webhook_events": {
      "payment": { "success": true },
      "payout": { "failed": false }
    }
  }'
```

Una respuesta exitosa incluye `"webhook_events"` en `updated_fields`:

```json
{
  "business_id": "PAY-001",
  "updated_fields": ["webhook_events"]
}
```

Los eventos admitidos para editar son:

| Tipo           | Eventos                                                                                                                                                        |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `payment`      | `created`, `success`, `accepted`, `review`, `overdue`, `edit`, `failed`, `blocked`, `cancel`, `credit`, `external`, `ret_pending`, `ret_review`, `ret_success` |
| `payout`       | `created`, `approved`, `success`, `edit`, `failed`, `cancel`                                                                                                   |
| `subscription` | `activated`, `overdue`, `canceled`, `fulfilled`                                                                                                                |
| `team`         | `limit`, `blocked`, `active`, `created`, `edit`                                                                                                                |
| `business`     | `registered`, `activated`, `rejected`, `edit`                                                                                                                  |

Para recibir las notificaciones de creación y aprobación de dispersiones, envía este cuerpo en el mismo `PATCH`. [Eventos de dispersiones](https://docs.qentaz.com/documentation/webhooks/eventos-de-dispersiones.md#creacion-y-aprobacion).

```json
{
  "webhook_events": {
    "payout": { "created": true, "approved": true }
  }
}
```

Los valores históricos `payment.refund` y `payment.chargeback` pueden aparecer en la consulta si están guardados, pero no se admiten en este PATCH. Habilitar un evento no crea por sí mismo el proceso que lo emite.

## Consultar configuración

<mark style="color:blue;">`GET`</mark> `/v1/business/webhook`

La credencial requiere permiso **GET** para esta ruta; las credenciales `system` conservan su excepción general. El negocio se selecciona de la misma manera que en el PATCH: omite `child-id` para el negocio del token o envía el identificador de una cuenta administrada autorizada.

```bash
curl --request GET '{{base_url}}/v1/business/webhook' \
  --header 'x-auth-token: YOUR_TOKEN' \
  --header 'child-id: PAY-CHILD-001'
```

Ejemplo de respuesta **200** (eventos abreviados):

```json
{
  "business_id": "PAY-CHILD-001",
  "webhook_url": "https://eje***hook",
  "custom_header": { "key": "test-token" },
  "webhook_events": {
    "payment": { "success": true, "failed": false },
    "payout": { "created": true }
  }
}
```

El encabezado solo muestra su nombre, nunca su valor. Si no hay URL o encabezado, el campo correspondiente es `null`.

`webhook_events` devuelve todo el contenido guardado, incluidos valores históricos, sin completar eventos ausentes. Si no hay configuración, devuelve `null`. En la entrega habitual solo `true` habilita el evento; los estados ausentes se consideran deshabilitados.

La consulta puede responder **401** si falta el token o es inválido, **403** si no tiene permiso o acceso a la cuenta y **404** si el negocio no existe.

Para eventos de cuentas administradas que se envían al partner, se utiliza la configuración de eventos y webhook del partner; configurar el hijo no modifica la del partner.

## Entrega de eventos

El flujo habitual de eventos utiliza la URL del negocio y envía el encabezado personalizado cuando está configurado. `payment:external` utiliza una lógica independiente y no ofrece la misma interpretación de nombre y valor.
