> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cucu.bo/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks de Merchant

> Registra, prueba y elimina la URL de tu servidor para recibir eventos en tiempo real.

Registra la URL de tu servidor para recibir eventos en tiempo real. Ver [Webhooks Salientes](/payments/crypto/webhooks) para el formato de los eventos y la verificación de firma.

## POST /merchants/me/webhook — Registrar o Rotar URL

### Headers

| Header         | Tipo   | Req | Descripción          |
| -------------- | ------ | --- | -------------------- |
| `X-API-Key`    | string | Sí  | API Key del merchant |
| `Content-Type` | string | Sí  | `application/json`   |

### Request Body

| Campo                    | Tipo   | Req | Descripción                                                                          |
| ------------------------ | ------ | --- | ------------------------------------------------------------------------------------ |
| `url`                    | string | Sí  | URL HTTPS donde CUCU enviará los eventos. Debe ser accesible desde internet.         |
| `secret`                 | string | No  | Secreto para firmar los webhooks. Si se omite, CUCU genera uno automáticamente.      |
| `events`                 | array  | No  | Lista de eventos a suscribir. Si se omite, se suscriben todos.                       |
| `rotation_grace_seconds` | int    | No  | Segundos que el secreto anterior sigue válido durante una rotación. Default: `3600`. |

### Response

| Campo     | Tipo    | Descripción                                                                     |
| --------- | ------- | ------------------------------------------------------------------------------- |
| `url`     | string  | URL registrada.                                                                 |
| `events`  | array   | Eventos suscritos.                                                              |
| `rotated` | boolean | `true` si se rotó el secreto.                                                   |
| `secret`  | string  | Secreto de firma. **Solo aparece en el registro inicial o rotación. Guárdalo.** |

<RequestExample>
  ```bash cURL theme={"system"}
  curl -X POST https://crypto.cucu.ai/api/v1/merchants/me/webhook \
    -H "X-API-Key: sk_live_xxxx" \
    -H "Content-Type: application/json" \
    -d '{
      "url": "https://tu-servidor.com/webhooks/cucu-crypto",
      "events": ["payment.confirmed", "payment.failed", "charge.expired", "charge.cancelled"]
    }'
  ```

  ```javascript JavaScript theme={"system"}
  const response = await fetch(
    'https://crypto.cucu.ai/api/v1/merchants/me/webhook',
    {
      method: 'POST',
      headers: { 'X-API-Key': 'sk_live_xxxx', 'Content-Type': 'application/json' },
      body: JSON.stringify({
        url: 'https://tu-servidor.com/webhooks/cucu-crypto',
        events: ['payment.confirmed', 'payment.failed', 'charge.expired', 'charge.cancelled']
      })
    }
  );
  const data = await response.json();
  ```

  ```python Python theme={"system"}
  import requests

  response = requests.post(
      'https://crypto.cucu.ai/api/v1/merchants/me/webhook',
      headers={'X-API-Key': 'sk_live_xxxx', 'Content-Type': 'application/json'},
      json={
          'url': 'https://tu-servidor.com/webhooks/cucu-crypto',
          'events': ['payment.confirmed', 'payment.failed', 'charge.expired', 'charge.cancelled']
      }
  )
  print(response.json())
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={"system"}
  {
    "url": "https://tu-servidor.com/webhooks/cucu-crypto",
    "events": ["payment.confirmed", "payment.failed", "charge.expired", "charge.cancelled"],
    "rotated": false,
    "secret": "wh_sk_xxxxxxxxxxxxxxxxxxxx"
  }
  ```
</ResponseExample>

***

## POST /merchants/me/webhook/test — Probar Webhook

Envía un evento sintético `webhook.test` a tu URL registrada para verificar la integración end-to-end.

```bash theme={"system"}
curl -X POST https://crypto.cucu.ai/api/v1/merchants/me/webhook/test \
  -H "X-API-Key: sk_live_xxxx"
```

**Response `202 Accepted`**

```json theme={"system"}
{
  "delivery_id": "d4e5f6a7-b8c9-0123-defa-456789abcdef",
  "status": "enqueued"
}
```

***

## DELETE /merchants/me/webhook — Eliminar Webhook

```bash theme={"system"}
curl -X DELETE https://crypto.cucu.ai/api/v1/merchants/me/webhook \
  -H "X-API-Key: sk_live_xxxx"
```

**Response:** `204 No Content`