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

# Crear webhook

> Registra una nueva URL para recibir notificaciones de eventos de tu cuenta.

Al crear un webhook recibirás un `secret` único. Úsalo para [verificar la firma](/client/webhooks/index#verificación-de-firma) de cada notificación entrante.

<Warning>
  El `secret` solo se muestra al momento de creación. Guárdalo de forma segura porque no podrás recuperarlo después.
</Warning>

### Body

<ParamField body="name" type="string" required>
  Nombre descriptivo del webhook (máx. 255 caracteres).
</ParamField>

<ParamField body="description" type="string">
  Descripción opcional del webhook (máx. 500 caracteres).
</ParamField>

<ParamField body="url" type="string" required>
  URL HTTPS donde OnePay enviará las notificaciones. Debe ser una URL válida y accesible.
</ParamField>

<ParamField body="events" type="array" required>
  Lista de eventos a escuchar. Debe contener al menos un evento.
  [Ver todos los eventos disponibles](/client/webhooks/index#eventos-disponibles).

  Ejemplos de valores válidos: `payment.approved`, `charge.paid`, `cashout.completed`.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl https://api.onepay.la/v1/webhooks \
    -X POST \
    -H "Authorization: Bearer sk_test_xxx" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Webhook de producción",
      "description": "Notificaciones de pagos y dispersiones",
      "url": "https://mi-servidor.com/webhooks/onepay",
      "events": [
        "payment.approved",
        "payment.rejected",
        "charge.paid",
        "charge.failed",
        "cashout.completed"
      ]
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.onepay.la/v1/webhooks', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer sk_test_xxx',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Webhook de producción',
      description: 'Notificaciones de pagos y dispersiones',
      url: 'https://mi-servidor.com/webhooks/onepay',
      events: [
        'payment.approved',
        'payment.rejected',
        'charge.paid',
        'charge.failed',
        'cashout.completed'
      ]
    })
  });

  const webhook = await response.json();
  // Guarda webhook.data.secret de forma segura
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.onepay.la/v1/webhooks',
      headers={
          'Authorization': 'Bearer sk_test_xxx',
          'Content-Type': 'application/json'
      },
      json={
          'name': 'Webhook de producción',
          'description': 'Notificaciones de pagos y dispersiones',
          'url': 'https://mi-servidor.com/webhooks/onepay',
          'events': [
              'payment.approved',
              'payment.rejected',
              'charge.paid',
              'charge.failed',
              'cashout.completed'
          ]
      }
  )

  webhook = response.json()
  # Guarda webhook['data']['secret'] de forma segura
  ```

  ```php PHP theme={null}
  <?php
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://api.onepay.la/v1/webhooks",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
      "Authorization: Bearer sk_test_xxx",
      "Content-Type: application/json"
    ],
    CURLOPT_POSTFIELDS => json_encode([
      "name" => "Webhook de producción",
      "description" => "Notificaciones de pagos y dispersiones",
      "url" => "https://mi-servidor.com/webhooks/onepay",
      "events" => [
        "payment.approved",
        "payment.rejected",
        "charge.paid",
        "charge.failed",
        "cashout.completed"
      ]
    ])
  ]);

  $response = curl_exec($curl);
  $webhook = json_decode($response, true);
  // Guarda $webhook['data']['secret'] de forma segura
  ?>
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={null}
  {
    "data": {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Webhook de producción",
      "description": "Notificaciones de pagos y dispersiones",
      "url": "https://mi-servidor.com/webhooks/onepay",
      "events": [
        "payment.approved",
        "payment.rejected",
        "charge.paid",
        "charge.failed",
        "cashout.completed"
      ],
      "secret": "whsec_abcdef1234567890abcdef1234567890",
      "header": null,
      "is_test": false,
      "created_at": "2025-01-20T14:30:00+00:00",
      "updated_at": "2025-01-20T14:30:00+00:00"
    }
  }
  ```

  ```json 422 theme={null}
  {
    "message": "El campo nombre es obligatorio. (y 2 errores más)",
    "code": 10001,
    "code_name": "validation_error",
    "errors": {
      "name": ["El campo nombre es obligatorio."],
      "url": ["El campo url es obligatorio."],
      "events": ["El campo events es obligatorio."]
    }
  }
  ```
</ResponseExample>