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

# Crear un webhook

> Registra una URL de callback para recibir notificaciones de eventos en tiempo real sobre órdenes, actividad de fondeo, pagos globales, pagos con stablecoins o retiros de cripto.

Usa este endpoint para registrar una URL de webhook a la que VelaFi llamará cuando ocurra un tipo de evento específico. Cada registro corresponde a un solo tipo de evento, así que crea webhooks separados para cada evento que quieras recibir. La solicitud se rechaza si ya existe un webhook activo para ese tipo de evento. Los webhooks pertenecen a tu cuenta, así que un webhook recibe su evento para todos los comercios de la cuenta. La respuesta incluye una `publicKey` que debes guardar: se usa para verificar la firma RSA-SHA256 de todas las entregas posteriores de webhooks a este endpoint.

> [!NOTE]
>
> Todas las solicitudes deben incluir el header `X-BH-TOKEN` y `Content-Type: application/json`. Guarda de forma segura la `publicKey` de la respuesta. También la devuelve [Listar webhooks](https://docs.velafi.com/es/api-reference/webhooks/get-webhook-endpoints.md).

## Endpoint

`POST https://api.velafi.com/v2/webhook`

## Parámetros de la solicitud

**eventType** `string` *required*

El tipo de evento que debe recibir este webhook. Valores aceptados:

* `ORDER_WEBHOOK` — cambios de estado de órdenes fiat/cripto
* `GLOBAL_PAYMENT_WEBHOOK` — cambios de estado de pagos globales fiat/fiat
* `FUNDING_WEBHOOK` — actividad de la cuenta Pending Fund
* `ON_RAMP_WITHDRAW_WEBHOOK` — el retiro de cripto a la billetera de destino de una orden de on-ramp por API completada fue exitoso
* `STABLE_COIN_PAYMENT_WEBHOOK` — se confirmó una orden de pago con stablecoins
* `CRYPTO_WITHDRAW_WEBHOOK` — un retiro de cripto desde la billetera de un comercio fue exitoso, falló o se canceló

**url** `string` *required*

La URL de acceso público a la que VelaFi enviará con POST las notificaciones de eventos. Debe empezar con `http`. Usa una URL `https://`.

## Campos de la respuesta

**code** `number`

Código de respuesta de tipo HTTP. `200` indica éxito.

**msg** `string`

Mensaje de estado legible, por ejemplo `SUCCESS`.

**data** `object`

**campos de data**

**webhookId** `string`

Identificador único de este registro de webhook.

**eventType** `string`

El tipo de evento para el que está registrado este webhook.

**url** `string`

La URL de callback registrada.

**status** `number`

Estado del webhook: `10` = activo, `20` = deshabilitado, `30` = eliminado.

**publicKey** `string`

Clave pública RSA codificada en Base64 que se usa para verificar el header `signature` de las solicitudes de webhook entrantes. También la devuelve [Listar webhooks](https://docs.velafi.com/es/api-reference/webhooks/get-webhook-endpoints.md).

## Ejemplo

```bash cURL theme={null}
curl -X POST https://api.velafi.com/v2/webhook \
  -H "X-BH-TOKEN: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "eventType": "ORDER_WEBHOOK",
    "url": "https://your-app.com/webhooks/velafi"
  }'
```

```json Response theme={null}
{
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "webhookId": "ebab8a9663704e7cbbebe672c7c67912",
    "eventType": "ORDER_WEBHOOK",
    "url": "https://your-app.com/webhooks/velafi",
    "status": 10,
    "publicKey": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAp/6GRTIrl+kQb9u27cGz..."
  }
}
```

> [!WARNING]
>
> Si pierdes la `publicKey`, obtenla con [Listar webhooks](https://docs.velafi.com/es/api-reference/webhooks/get-webhook-endpoints.md). Consulta [Configuración de webhooks](https://docs.velafi.com/es/api-reference/webhooks/webhook-setup.md) para ver cómo usar la clave pública para verificar las solicitudes entrantes.


## Related topics

- [Crear un comercio](https://docs.velafi.com/es/docs/guides/creating-merchant.md)
- [Crear un retiro cripto](https://docs.velafi.com/es/api-reference/crypto-wallet/create-crypto-withdrawal.md)
- [Eliminar un webhook](https://docs.velafi.com/es/api-reference/webhooks/delete-a-webhook.md)
- [Actualizar un webhook](https://docs.velafi.com/es/api-reference/webhooks/update-a-webhook.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.