Webhook Management

Manage your webhook endpoints to receive real-time event notifications. You can register up to 10 webhook endpoints per organization.

Create Webhook

POST /webhooks

Request Body

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

Field	Type	Required	Description
`url`	string	Yes	HTTPS endpoint URL to receive webhook deliveries
`events`	string[]	Yes	Array of event types to subscribe to (or `["*"]` for all)
`description`	string	No	A human-readable description for this endpoint

Response (201 Created)

{
	"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"
}

Important: The signingSecret is only returned when the webhook is first created. Store it securely -- you will need it to verify incoming webhook signatures. It cannot be retrieved again.

SSRF Protection

Webhook URLs must be publicly accessible HTTPS endpoints. The following are rejected:

Private/internal IP addresses (10.x.x.x, 172.16-31.x.x, 192.168.x.x)
Localhost and loopback addresses
Non-HTTPS URLs

List Webhooks

GET /webhooks

Response

{
	"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"
		}
	]
}

Update Webhook

PUT /webhooks/:id

Path Parameters

Name	Type	Required	Description
`id`	string	Yes	The webhook ID

Request Body

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

All fields are optional. Only provided fields are updated.

Response

Returns the updated webhook object.

Delete Webhook

DELETE /webhooks/:id

Path Parameters

Name	Type	Required	Description
`id`	string	Yes	The webhook ID

Response

Returns 204 No Content on success.

Test Webhook

Send a test event to verify that your endpoint is reachable and correctly processing webhook deliveries.

POST /webhooks/:id/test

Path Parameters

Name	Type	Required	Description
`id`	string	Yes	The webhook ID

Response

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

If the test delivery fails:

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