Webhooks

Webhooks deliver events to your endpoint, signed with VenueRun-Signature (HMAC-SHA256 over timestamp.body).

Base URL: https://apiv2.venuerun.com/merchants/:merchantId/webhooks

text

GET    /merchants/:merchantId/webhooks
POST   /merchants/:merchantId/webhooks
GET    /merchants/:merchantId/webhooks/:webhookId
PATCH  /merchants/:merchantId/webhooks/:webhookId
DELETE /merchants/:merchantId/webhooks/:webhookId

The webhook object

Field	Type	Description
`id`	`string` (read-only)	Unique identifier, assigned by VenueRun.
`createdAt`	`string` (read-only)	When it was created (ISO 8601).
`updatedAt`	`string` (read-only)	When it last changed (ISO 8601).
`title`	`string`
`url`	`string`
`active`	`boolean`
`events`	`string[]`	Subscribed event names (e.g. `product.created`, `order.paid`). Defaults to `[]`.
`testMode`	`boolean`	Defaults to `false`.

json

{
  "id": "LvWIk0xN9aOpqItbcjxO",
  "title": "Test webhook A1B2C3",
  "url": "https://example.com/venuerun-test-receiver",
  "active": false,
  "events": [
    "order.created"
  ],
  "testMode": true,
  "createdAt": "2026-01-15T12:00:00.000Z",
  "updatedAt": "2026-01-15T12:00:00.000Z",
  "signingSecret": "[redacted]"
}

List webhooks

GET /merchants/:merchantId/webhooks

javascript

const merchantId = process.env.VENUERUN_MERCHANT_ID;
const response = await fetch(`https://apiv2.venuerun.com/merchants/${merchantId}/webhooks`, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.VENUERUN_API_KEY}`,
  },
});

Response:

json

{
  "testMode": true,
  "length": 1,
  "data": [
    {
      "id": "LvWIk0xN9aOpqItbcjxO",
      "title": "Test webhook A1B2C3",
      "url": "https://example.com/venuerun-test-receiver",
      "active": false,
      "events": [
        "order.created"
      ],
      "testMode": true,
      "createdAt": "2026-01-15T12:00:00.000Z",
      "updatedAt": "2026-01-15T12:00:00.000Z",
      "signingSecret": "[redacted]"
    }
  ]
}

Create a webhook

POST /merchants/:merchantId/webhooks

Required attributes

Field	Type	Description
`title`	`string`
`url`	`string`
`active`	`boolean`
`events`	`string[]`	Subscribed event names (e.g. `product.created`, `order.paid`).

Optional attributes

Field	Type	Description
`testMode`	`boolean`	Defaults to `false`.

javascript

const merchantId = process.env.VENUERUN_MERCHANT_ID;
const response = await fetch(`https://apiv2.venuerun.com/merchants/${merchantId}/webhooks`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VENUERUN_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "title": "Test webhook A1B2C3",
    "url": "https://example.com/venuerun-test-receiver",
    "active": false,
    "events": [
      "order.created"
    ],
    "testMode": true
  }),
});

Response:

json

{
  "id": "YQ8Ly4yjnyIRBL4P5N2H",
  "title": "Test webhook A1B2C3",
  "url": "https://example.com/venuerun-test-receiver",
  "active": false,
  "events": [
    "order.created"
  ],
  "testMode": true,
  "createdAt": "2026-01-15T12:00:00.000Z",
  "updatedAt": "2026-01-15T12:00:00.000Z",
  "signingSecret": "[redacted]"
}

Retrieve a webhook

GET /merchants/:merchantId/webhooks/:webhookId

javascript

const merchantId = process.env.VENUERUN_MERCHANT_ID;
const response = await fetch(`https://apiv2.venuerun.com/merchants/${merchantId}/webhooks/2NRYzPmzDLt62mAhSQrc`, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.VENUERUN_API_KEY}`,
  },
});

Response:

json

{
  "id": "2NRYzPmzDLt62mAhSQrc",
  "title": "Test webhook A1B2C3",
  "url": "https://example.com/venuerun-test-receiver",
  "active": false,
  "events": [
    "order.created"
  ],
  "testMode": true,
  "createdAt": "2026-01-15T12:00:00.000Z",
  "updatedAt": "2026-01-15T12:00:00.000Z",
  "signingSecret": "[redacted]"
}

Update a webhook

PATCH /merchants/:merchantId/webhooks/:webhookId

Send only the fields you are changing — every attribute is optional.

javascript

const merchantId = process.env.VENUERUN_MERCHANT_ID;
const response = await fetch(`https://apiv2.venuerun.com/merchants/${merchantId}/webhooks/DNj01kfO1zDEZMmAlioB`, {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.VENUERUN_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "testMode": false
  }),
});

Response:

json

{
  "id": "DNj01kfO1zDEZMmAlioB",
  "title": "Test webhook A1B2C3",
  "url": "https://example.com/venuerun-test-receiver",
  "active": false,
  "events": [
    "order.created"
  ],
  "testMode": true,
  "createdAt": "2026-01-15T12:00:00.000Z",
  "updatedAt": "2026-01-15T12:00:00.000Z"
}

Delete a webhook

DELETE /merchants/:merchantId/webhooks/:webhookId

javascript

const merchantId = process.env.VENUERUN_MERCHANT_ID;
const response = await fetch(`https://apiv2.venuerun.com/merchants/${merchantId}/webhooks/fbzSk3hfpTotAtrCu2kg`, {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${process.env.VENUERUN_API_KEY}`,
  },
});

Response:

json

{
  "id": "fbzSk3hfpTotAtrCu2kg",
  "object": {
    "id": "fbzSk3hfpTotAtrCu2kg",
    "title": "Test webhook A1B2C3",
    "url": "https://example.com/venuerun-test-receiver",
    "active": false,
    "events": [
      "order.created"
    ],
    "testMode": true,
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-01-15T12:00:00.000Z"
  },
  "message": "Webhook deleted",
  "deleted": true
}

Errors

Every error answers with a message. A request that fails validation is a 400:

json

{
  "message": "An API key in test mode cannot create a live mode webhook."
}