Crear un webhook

Autorización

apiKey webhooks.write

AutorizaciónBearer <token>

La llave del negocio, creada en el panel: Integraciones → API pública. vk_live_… es una llave real; vk_test_…, una llave de modo prueba (verificaciones simuladas, nada toca el libro real). Ver la guía «Modo de prueba».

Va en: header

Permiso: webhooks.write

Parámetros de consulta

companyId?string

Sobre qué negocio actúa la petición. Obligatorio solo si la llave entra a varios negocios; con uno solo, se deduce.

Cuerpo de la petición

application/json

Tipos de TypeScript

Usa el tipo request body en TypeScript.

url*string

A dónde mandamos los eventos. Tiene que ser https y resolver a una dirección pública.

Formatouri

description?string

Para ti: «producción», «staging», «el ERP del contador». Sale en la lista del panel.

events*array<string>

Qué eventos quieres recibir. Claves del catálogo (GET /v1/webhook-events). Al menos uno — un webhook sin eventos no recibiría nada.

Elementos1 <= items

auth?

Con qué credencial llamamos a tu endpoint. No sustituye a la firma: la credencial abre la puerta de un endpoint que no está abierto al mundo; Verifika-Signature sigue siendo lo que prueba que el evento es nuestro. Se guarda cifrada (AES-256-GCM) y nunca vuelve a salir por la API: en las respuestas solo va el resumen (type, y username/headerName, que no son secretos).

headers?array<>

Cabeceras propias que mandamos en cada entrega, además de las nuestras. Para enrutar del otro lado (a qué inquilino, a qué entorno), no para credenciales — para eso está auth. Se guardan cifradas. No se pueden usar Content-Type, User-Agent, Host, Content-Length, Authorization ni nada que empiece por Verifika-.

Elementositems <= 10

testEvents?boolean

«Recibir también eventos de prueba». Los eventos de las llaves vk_test_ solo van a los endpoints que lo tengan encendido.

Por defectofalse

Cuerpo de la respuesta

`application/json`

curl -X POST "https://example.com/webhook-endpoints" \  -H "Content-Type: application/json" \  -d '{    "url": "https://tusistema.com/verifika",    "description": "Producción",    "events": [      "income.verified",      "suspicious.created"    ],    "auth": {      "type": "API_KEY",      "headerName": "X-Api-Key",      "value": "…",      "prefix": null    },    "headers": [      {        "name": "X-Tenant-Id",        "value": "acme"      }    ]  }'

{  "object": "webhookEndpoint",  "id": "string",  "url": "http://example.com",  "description": "string",  "events": [    "string"  ],  "auth": {    "type": "NONE",    "username": "string",    "headerName": "string"  },  "headerNames": [    "string"  ],  "status": "ENABLED",  "consecutiveFailures": 0,  "lastSuccessAt": "string",  "lastFailureAt": "string",  "createdAt": "string",  "last24h": {    "delivered": 0,    "failed": 0  },  "testEvents": true,  "secret": "string"}

Autorización

Parámetros de consulta

Cuerpo de la petición

Cuerpo de la respuesta

201application/json

400application/json

401application/json

403application/json

`application/json`

`application/json`

`application/json`

`application/json`