Api Reference

Webhook Endpoints

Register and manage the endpoints Vatly delivers webhook events to — create, list, update, and delete them programmatically.

The Webhook Endpoint API Resource

A webhook endpoint is the URL Vatly POSTs event deliveries to. Each delivery is signed with the secret you set (see the Vatly-Signature header in the Webhooks guide).

A storefront can have up to five endpoints per mode (test and live are separate; the mode is determined by the API token you use). Each endpoint carries its own enabledEvents subscription list, so you can fan different events out to different URLs. Managing endpoints from the API is useful for provisioning from CI / infrastructure-as-code, or pointing an ephemeral preview environment at its own public URL.

The signing secret is write-only: you supply it on creation (and may rotate it via update), but it is never returned in any response. Store the value you send — the API will not give it back.

Properties

Name	Type	Description
`id`	`string`	Unique identifier for the webhook endpoint (starts with `webhook_`).
`resource`	`string`	The resource type. Always `webhook_endpoint`.
`testmode`	`boolean`	Whether this endpoint receives test-mode events.
`url`	`string`	The HTTPS URL deliveries are POSTed to.
`enabledEvents`	`array`	The event names this endpoint is subscribed to. Only these are delivered. An empty list means the endpoint is dormant (no domain events) — though the `webhook.setup` verification event is always sent regardless. New event names are not added automatically; update the endpoint to opt in. See the event types for the subscribable names.
`createdAt`	`string`	When this endpoint was created (ISO 8601 format).
`links`	`object`	HATEOAS links to related resources. Contains `self`.

List webhook endpoints

GET /v1/webhook-endpoints

Returns the webhook endpoints for the authenticated storefront, filtered by the testmode determined from the API token (up to five per mode). Each endpoint includes its enabledEvents subscriptions; the signing secret is never included.

Optional attributes

Name	Type	Description
`limit`	`integer`	The number of endpoints to return (default: 10, max: 100).
`startingAfter`	`string`	A cursor for use in pagination. Returns results after this endpoint ID.
`endingBefore`	`string`	A cursor for use in pagination. Returns results before this endpoint ID.

curl -G https://api.vatly.com/v1/webhook-endpoints \
  -H "Authorization: Bearer live_your_api_key_here"

$vatly = new \Vatly\API\VatlyApiClient();
$vatly->setApiKey('live_your_api_key_here');

$endpoints = $vatly->webhookEndpoints->page();

{
  "data": [
    {
      "id": "webhook_QdEpFhdSrG4Y3DnfsdqsH",
      "resource": "webhook_endpoint",
      "testmode": false,
      "url": "https://merchant.example/webhooks/vatly",
      "enabledEvents": [
        "order.paid",
        "refund.completed"
      ],
      "createdAt": "2024-01-15T10:30:00Z",
      "links": {
        "self": {
          "href": "https://api.vatly.com/v1/webhook-endpoints/webhook_QdEpFhdSrG4Y3DnfsdqsH",
          "type": "application/json"
        }
      }
    },
    {
      "id": "webhook_Vm6zTjNsKp9LcRwXyBaF",
      "resource": "webhook_endpoint",
      "testmode": false,
      "url": "https://analytics.example/webhooks/vatly",
      "enabledEvents": [
        "checkout.paid"
      ],
      "createdAt": "2024-02-10T08:15:00Z",
      "links": {
        "self": {
          "href": "https://api.vatly.com/v1/webhook-endpoints/webhook_Vm6zTjNsKp9LcRwXyBaF",
          "type": "application/json"
        }
      }
    }
  ],
  "count": 2,
  "links": {
    "self": {
      "href": "https://api.vatly.com/v1/webhook-endpoints",
      "type": "application/json"
    },
    "next": null,
    "prev": null
  }
}

Register a webhook endpoint

POST /v1/webhook-endpoints

Registers a webhook endpoint for the mode determined by the API token.

You supply the signing secret; it is write-only and never returned, so keep the value you send — you use it to verify the Vatly-Signature HMAC on deliveries.

Vatly sends a webhook.setup verification ping to the URL and validates its SSL certificate; if either fails the request is rejected with 422. A storefront may register up to five endpoints per mode, and each URL must be unique within that storefront and mode — a duplicate URL or a sixth endpoint returns 422.

enabledEvents is an explicit snapshot. If omitted, Vatly stores every event name available at registration time; events introduced later are not enabled automatically. Send [] for a dormant endpoint. The webhook.setup verification event is unconditional and cannot be selected.

Required attributes

Name	Type	Description
`url`	`string`	The HTTPS URL deliveries are POSTed to. Must be publicly reachable and present a valid SSL certificate. `localhost` and loopback addresses are not allowed. Must be unique within the storefront and mode.
`secret`	`string`	Signing secret for this endpoint (at least 10 characters), used to compute the `Vatly-Signature` HMAC on every delivery. You choose it (e.g. pinned from an environment variable). Write-only — the API never returns it.

Optional attributes

Name	Type	Description
`enabledEvents`	`array`	The event names to deliver to this endpoint, drawn from the subscribable set (see event types). Omit to subscribe to every event available at registration time; send `[]` for a dormant endpoint. `webhook.setup` is always sent and cannot be listed here.

curl https://api.vatly.com/v1/webhook-endpoints \
  -H "Authorization: Bearer live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://merchant.example/webhooks/vatly",
    "secret": "whsec_3f9a1c7e2d4f7b9c5a2c1d5b7e9f3a8d",
    "enabledEvents": ["order.paid", "refund.completed"]
  }'

$vatly = new \Vatly\API\VatlyApiClient();
$vatly->setApiKey('live_your_api_key_here');

$endpoint = $vatly->webhookEndpoints->create([
  'url' => 'https://merchant.example/webhooks/vatly',
  'secret' => 'whsec_3f9a1c7e2d4f7b9c5a2c1d5b7e9f3a8d',
  'enabledEvents' => ['order.paid', 'refund.completed'],
]);

{
  "id": "webhook_QdEpFhdSrG4Y3DnfsdqsH",
  "resource": "webhook_endpoint",
  "testmode": false,
  "url": "https://merchant.example/webhooks/vatly",
  "enabledEvents": [
    "order.paid",
    "refund.completed"
  ],
  "createdAt": "2024-01-15T10:30:00Z",
  "links": {
    "self": {
      "href": "https://api.vatly.com/v1/webhook-endpoints/webhook_QdEpFhdSrG4Y3DnfsdqsH",
      "type": "application/json"
    }
  }
}

Get a webhook endpoint

GET /v1/webhook-endpoints/:id

Retrieves a webhook endpoint by ID. The signing secret is never included.

Parameters

Name	Type	Description
`webhookEndpointId`	`string`	The unique identifier of the webhook endpoint.

curl https://api.vatly.com/v1/webhook-endpoints/webhook_QdEpFhdSrG4Y3DnfsdqsH \
  -H "Authorization: Bearer live_your_api_key_here"

$vatly = new \Vatly\API\VatlyApiClient();
$vatly->setApiKey('live_your_api_key_here');

$endpoint = $vatly->webhookEndpoints->get('webhook_QdEpFhdSrG4Y3DnfsdqsH');

{
  "id": "webhook_QdEpFhdSrG4Y3DnfsdqsH",
  "resource": "webhook_endpoint",
  "testmode": false,
  "url": "https://merchant.example/webhooks/vatly",
  "enabledEvents": [
    "order.paid",
    "refund.completed"
  ],
  "createdAt": "2024-01-15T10:30:00Z",
  "links": {
    "self": {
      "href": "https://api.vatly.com/v1/webhook-endpoints/webhook_QdEpFhdSrG4Y3DnfsdqsH",
      "type": "application/json"
    }
  }
}

Update a webhook endpoint

PATCH /v1/webhook-endpoints/:id

Updates a webhook endpoint's url, its signing secret, and/or its complete enabledEvents subscription set. A new URL is revalidated for reachability and a valid SSL certificate just like on creation. The secret is write-only and is never returned.

Omitting enabledEvents preserves the current subscriptions; sending [] makes the endpoint dormant; sending a list replaces the whole set. Sending an empty body is a no-op that returns the current endpoint.

Optional attributes

Name	Type	Description
`url`	`string`	New HTTPS delivery URL. Revalidated for reachability and SSL the same way as on creation; must stay unique within the storefront and mode.
`secret`	`string`	New signing secret (at least 10 characters). Write-only — keep the value, as the API never returns it.
`enabledEvents`	`array`	Replaces the endpoint's complete event subscription set (see event types). Omit to preserve the current set; send `[]` to make the endpoint dormant. New event names are never added automatically; `webhook.setup` is not subscribable.

curl -X PATCH https://api.vatly.com/v1/webhook-endpoints/webhook_QdEpFhdSrG4Y3DnfsdqsH \
  -H "Authorization: Bearer live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://merchant.example/webhooks/vatly-v2",
    "enabledEvents": ["checkout.paid", "order.paid"]
  }'

$vatly = new \Vatly\API\VatlyApiClient();
$vatly->setApiKey('live_your_api_key_here');

$endpoint = $vatly->webhookEndpoints->update('webhook_QdEpFhdSrG4Y3DnfsdqsH', [
  'url' => 'https://merchant.example/webhooks/vatly-v2',
  'enabledEvents' => ['checkout.paid', 'order.paid'],
]);

{
  "id": "webhook_QdEpFhdSrG4Y3DnfsdqsH",
  "resource": "webhook_endpoint",
  "testmode": false,
  "url": "https://merchant.example/webhooks/vatly-v2",
  "enabledEvents": [
    "checkout.paid",
    "order.paid"
  ],
  "createdAt": "2024-01-15T10:30:00Z",
  "links": {
    "self": {
      "href": "https://api.vatly.com/v1/webhook-endpoints/webhook_QdEpFhdSrG4Y3DnfsdqsH",
      "type": "application/json"
    }
  }
}

Delete a webhook endpoint

DELETE /v1/webhook-endpoints/:id

Deletes a webhook endpoint. Vatly stops sending deliveries to it immediately. To receive events again, register a new endpoint.

Parameters

Name	Type	Description
`webhookEndpointId`	`string`	The unique identifier of the webhook endpoint.

curl -X DELETE https://api.vatly.com/v1/webhook-endpoints/webhook_QdEpFhdSrG4Y3DnfsdqsH \
  -H "Authorization: Bearer live_your_api_key_here"

$vatly = new \Vatly\API\VatlyApiClient();
$vatly->setApiKey('live_your_api_key_here');

$vatly->webhookEndpoints->delete('webhook_QdEpFhdSrG4Y3DnfsdqsH');

Returns 204 No Content on success.

Edit this pageorReport an issue

Customers

On this page, we'll dive into the different customer endpoints you can use to manage your Vatly customers programmatically.

Test helpers

Simulate subscription renewals in test mode so you can verify recurring billing flows end to end.