Gestión de webhooks

Gestione sus endpoints de webhook para recibir notificaciones de eventos en tiempo real. Puede registrar hasta 10 endpoints de webhook por organización.

Crear webhook

text

POST /webhooks

Cuerpo de la solicitud

json

{
	"url": "https://yourapp.com/webhooks/vignetim",
	"events": ["order.completed", "order.failed"],
	"description": "Production order notifications"
}

Campo	Tipo	Requerido	Descripción
`url`	string	Sí	URL del endpoint HTTPS para recibir entregas de webhook
`events`	string[]	Sí	Array de tipos de eventos a los que suscribirse (o `["*"]` para todos)
`description`	string	No	Una descripción legible para este endpoint

Respuesta (201 Created)

json

{
	"id": "wh-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
	"url": "https://yourapp.com/webhooks/vignetim",
	"events": ["order.completed", "order.failed"],
	"description": "Production order notifications",
	"active": true,
	"signingSecret": "whs_a1b2c3d4e5f6789012345678901234567890abcdef",
	"createdAt": "2026-03-20T14:30:00.000Z"
}

Importante: El signingSecret solo se devuelve cuando el webhook se crea por primera vez. Almacénelo de forma segura -- lo necesitará para verificar las firmas de los webhooks entrantes. No se puede recuperar nuevamente.

Protección SSRF

Las URLs de webhook deben ser endpoints HTTPS accesibles públicamente. Los siguientes son rechazados:

Direcciones IP privadas/internas (10.x.x.x, 172.16-31.x.x, 192.168.x.x)
Direcciones localhost y loopback
URLs no HTTPS

Listar webhooks

text

GET /webhooks

Respuesta

json

{
	"data": [
		{
			"id": "wh-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
			"url": "https://yourapp.com/webhooks/vignetim",
			"events": ["order.completed", "order.failed"],
			"description": "Production order notifications",
			"active": true,
			"consecutiveFailures": 0,
			"createdAt": "2026-03-20T14:30:00.000Z",
			"updatedAt": "2026-03-20T14:30:00.000Z"
		}
	]
}

Actualizar webhook

text

PUT /webhooks/:id

Parámetros de ruta

Nombre	Tipo	Requerido	Descripción
`id`	string	Sí	El ID del webhook

Cuerpo de la solicitud

json

{
	"url": "https://yourapp.com/webhooks/vignetim-v2",
	"events": ["*"],
	"description": "Updated to receive all events"
}

Todos los campos son opcionales. Solo se actualizan los campos proporcionados.

Respuesta

Devuelve el objeto de webhook actualizado.

Eliminar webhook

text

DELETE /webhooks/:id

Parámetros de ruta

Nombre	Tipo	Requerido	Descripción
`id`	string	Sí	El ID del webhook

Respuesta

Devuelve 204 No Content en caso de éxito.

Probar webhook

Envíe un evento de prueba para verificar que su endpoint es accesible y procesa correctamente las entregas de webhook.

text

POST /webhooks/:id/test

Parámetros de ruta

Nombre	Tipo	Requerido	Descripción
`id`	string	Sí	El ID del webhook

Respuesta

json

{
	"success": true,
	"statusCode": 200,
	"responseTime": 145,
	"message": "Test webhook delivered successfully"
}

Si la entrega de prueba falla:

json

{
	"success": false,
	"statusCode": 500,
	"responseTime": 10000,
	"message": "Webhook endpoint returned non-2xx status code"
}