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).

There is at most one endpoint per mode — one for test and one for live — and the mode is determined by the API token you use. 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.
`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 merchant, filtered by the testmode determined from the API token. Because there is at most one endpoint per mode, this returns at most one endpoint. 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",
      "createdAt": "2024-01-15T10:30:00Z",
      "links": {
        "self": {
          "href": "https://api.vatly.com/v1/webhook-endpoints/webhook_QdEpFhdSrG4Y3DnfsdqsH",
          "type": "application/json"
        }
      }
    }
  ],
  "count": 1,
  "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. There is at most one endpoint per mode — registering a second one when the token's mode already has an endpoint returns 422; update or delete the existing one instead.

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.
`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.

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

$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',
]);

{
  "id": "webhook_QdEpFhdSrG4Y3DnfsdqsH",
  "resource": "webhook_endpoint",
  "testmode": false,
  "url": "https://merchant.example/webhooks/vatly",
  "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",
  "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, or both. 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. Sending an empty body is a no-op that returns the current endpoint.

Repointing the URL is the supported way to follow an ephemeral environment whose public URL changes between runs, without rotating the signing secret.

Optional attributes

Name	Type	Description
`url`	`string`	New HTTPS delivery URL. Revalidated for reachability and SSL the same way as on creation.
`secret`	`string`	New signing secret (at least 10 characters). Write-only — keep the value, as the API never returns it.

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

$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',
]);

{
  "id": "webhook_QdEpFhdSrG4Y3DnfsdqsH",
  "resource": "webhook_endpoint",
  "testmode": false,
  "url": "https://merchant.example/webhooks/vatly-v2",
  "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.