Docs
GitHubDiscord

The Webhook Endpoint object

You can configure webhook endpoints via the API to be notified about events that happen in your Zoneless platform. When an event occurs (such as a payout completing or an account being updated), Zoneless sends a POST request to your configured URL with the event data.

Stripe API equivalent
Create a webhook endpoint
POST /v1/webhook_endpoints
Update a webhook endpoint
POST /v1/webhook_endpoints/:id
Retrieve a webhook endpoint
GET /v1/webhook_endpoints/:id
List all webhook endpoints
GET /v1/webhook_endpoints
Delete a webhook endpoint
DELETE /v1/webhook_endpoints/:id

Each webhook endpoint can subscribe to specific event types, or use ['*'] to receive all events. The webhook payload contains the full Event object including the affected resource.

Attributes

id string

Unique identifier for the object. Zoneless webhook endpoint IDs are prefixed with we_z_.

object string

String representing the object's type. Objects of the same type share the same value. Always webhook_endpoint.

api_versionnullable string

The API version events are rendered as for this webhook endpoint.

applicationnullable string

The ID of the associated Connect application. Currently always null as OAuth applications are not yet supported.

created timestamp

Time at which the object was created. Measured in seconds since the Unix epoch.

descriptionnullable string

An optional description of what the webhook is used for.

enabled_events array of strings

The list of events to enable for this endpoint. ['*'] indicates that all events are enabled.

livemode boolean

Has the value true if the object exists in live mode or the value false if the object exists in test mode.

metadata object

Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

secret string

The endpoint's secret, used to generate webhook signatures. Only returned at creation. See Webhooks for information on verifying webhook signatures.

status enum

The status of the webhook.

Possible enum values
enabledThe webhook endpoint is active and will receive events.
disabledThe webhook endpoint is disabled and will not receive events.
url string

The URL of the webhook endpoint. Must use HTTPS in production.

More attributes

THE WEBHOOK ENDPOINT OBJECT
{
  "id": "we_z_1Mr5jULkdIwHu7ix",
  "object": "webhook_endpoint",
  "api_version": null,
  "application": null,
  "created": 1704067200,
  "description": "Webhook for payout notifications",
  "enabled_events": [
    "payout.paid",
    "payout.failed"
  ],
  "livemode": true,
  "metadata": {},
  "platform_account": "acct_z_Platform123abc",
  "secret": "whsec_z_wRNftLajMZNeslQOP6vEPm4iVx5NlZ6z",
  "status": "enabled",
  "url": "https://example.com/my/webhook/endpoint"
}

Create a webhook endpoint

A webhook endpoint must have a url and a list of enabled_events. When events matching those types occur in your platform, Zoneless will send a POST request to the specified URL.

ENDPOINTS
POST /v1/webhook_endpoints

Parameters

enabled_events array of enums Required

The list of events to enable for this endpoint. You may specify ['*'] to enable all events.

Possible enum values
*Subscribe to all events.
account.createdOccurs whenever a connected account is created.
account.updatedOccurs whenever an account status or property has changed.
balance.availableOccurs whenever your platform balance or a connected account balance has been updated (e.g., when a transfer is created or a payout is processed).
balance_transaction.createdOccurs whenever a new balance transaction is created (transfers, payouts, top-ups, etc.).
external_account.createdOccurs whenever an external wallet is created (a Solana wallet address added to receive USDC payouts).
external_account.updatedOccurs whenever an external wallet is updated.
external_account.deletedOccurs whenever an external wallet is deleted.
payout.createdOccurs whenever a payout is created.
payout.updatedOccurs whenever a payout is updated.
payout.paidOccurs whenever a payout is expected to be available in the destination wallet. The USDC has been sent on-chain to the connected account's Solana wallet.
payout.failedOccurs whenever a payout attempt fails. This can happen if the destination wallet is invalid or if there's an on-chain error.
payout.canceledOccurs whenever a payout is canceled.
person.createdOccurs whenever a person associated with an account is created.
person.updatedOccurs whenever a person associated with an account is updated.
person.deletedOccurs whenever a person associated with an account is deleted.
price.createdOccurs whenever a price is created.
price.updatedOccurs whenever a price is updated.
price.deletedOccurs whenever a price is deleted.
product.createdOccurs whenever a product is created.
product.updatedOccurs whenever a product is updated.
product.deletedOccurs whenever a product is deleted.
topup.createdOccurs whenever a top-up is created. Top-ups add USDC to your platform balance.
topup.succeededOccurs whenever a top-up succeeds and the USDC is available in your platform balance.
topup.failedOccurs whenever a top-up fails.
topup.canceledOccurs whenever a top-up is canceled.
topup.reversedOccurs whenever a top-up is reversed.
transfer.createdOccurs whenever a transfer is created. Transfers move funds from your platform balance to a connected account's balance.
transfer.updatedOccurs whenever a transfer's description or metadata is updated.
api_key.createdOccurs whenever a new API key is created for the platform.
api_key.updatedOccurs whenever an API key is updated (e.g., name changed or rolled).
api_key.deletedOccurs whenever an API key is deleted.
url string Required

The URL of the webhook endpoint. Must use HTTPS in production (HTTP is allowed in test mode for local development).

More attributes

Returns

Returns the webhook endpoint object with the secret field populated.

POST/v1/webhook_endpoints
import { Zoneless } from '@zoneless/node';
const zoneless = new Zoneless('sk_live_z_YOUR_API_KEY', 'https://api.zoneless.com');

const webhookEndpoint = await zoneless.webhookEndpoints.create({
  enabled_events: ['payout.paid', 'payout.failed'],
  url: 'https://example.com/my/webhook/endpoint',
});
RESPONSE
{
  "id": "we_z_1Mr5jULkdIwHu7ix",
  "object": "webhook_endpoint",
  "api_version": null,
  "application": null,
  "created": 1704067200,
  "description": null,
  "enabled_events": [
    "payout.paid",
    "payout.failed"
  ],
  "livemode": true,
  "metadata": {},
  "platform_account": "acct_z_Platform123abc",
  "secret": "whsec_z_wRNftLajMZNeslQOP6vEPm4iVx5NlZ6z",
  "status": "enabled",
  "url": "https://example.com/my/webhook/endpoint"
}

Update a webhook endpoint

Updates the webhook endpoint. You may edit the url, the list of enabled_events, and the status of your endpoint.

ENDPOINTS
POST /v1/webhook_endpoints/:id

Parameters

At least one parameter must be provided.

description string

An optional description of what the webhook is used for.

disabled boolean

Disable the webhook endpoint if set to true.

enabled_events array of enums

The list of events to enable for this endpoint. You may specify ['*'] to enable all events.

Possible enum values
*Subscribe to all events.
account.createdOccurs whenever a connected account is created.
account.updatedOccurs whenever an account status or property has changed.
balance.availableOccurs whenever your platform balance or a connected account balance has been updated (e.g., when a transfer is created or a payout is processed).
balance_transaction.createdOccurs whenever a new balance transaction is created (transfers, payouts, top-ups, etc.).
external_account.createdOccurs whenever an external wallet is created (a Solana wallet address added to receive USDC payouts).
external_account.updatedOccurs whenever an external wallet is updated.
external_account.deletedOccurs whenever an external wallet is deleted.
payout.createdOccurs whenever a payout is created.
payout.updatedOccurs whenever a payout is updated.
payout.paidOccurs whenever a payout is expected to be available in the destination wallet. The USDC has been sent on-chain to the connected account's Solana wallet.
payout.failedOccurs whenever a payout attempt fails. This can happen if the destination wallet is invalid or if there's an on-chain error.
payout.canceledOccurs whenever a payout is canceled.
person.createdOccurs whenever a person associated with an account is created.
person.updatedOccurs whenever a person associated with an account is updated.
person.deletedOccurs whenever a person associated with an account is deleted.
price.createdOccurs whenever a price is created.
price.updatedOccurs whenever a price is updated.
price.deletedOccurs whenever a price is deleted.
product.createdOccurs whenever a product is created.
product.updatedOccurs whenever a product is updated.
product.deletedOccurs whenever a product is deleted.
topup.createdOccurs whenever a top-up is created. Top-ups add USDC to your platform balance.
topup.succeededOccurs whenever a top-up succeeds and the USDC is available in your platform balance.
topup.failedOccurs whenever a top-up fails.
topup.canceledOccurs whenever a top-up is canceled.
topup.reversedOccurs whenever a top-up is reversed.
transfer.createdOccurs whenever a transfer is created. Transfers move funds from your platform balance to a connected account's balance.
transfer.updatedOccurs whenever a transfer's description or metadata is updated.
api_key.createdOccurs whenever a new API key is created for the platform.
api_key.updatedOccurs whenever an API key is updated (e.g., name changed or rolled).
api_key.deletedOccurs whenever an API key is deleted.
metadata object

Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

url string

The URL of the webhook endpoint.

Returns

Returns the updated webhook endpoint object if successful. Otherwise, this call raises an error.

POST/v1/webhook_endpoints/:id
import { Zoneless } from '@zoneless/node';
const zoneless = new Zoneless('sk_live_z_YOUR_API_KEY', 'https://api.zoneless.com');

const webhookEndpoint = await zoneless.webhookEndpoints.update(
  'we_z_1Mr5jULkdIwHu7ix',
  {
    enabled_events: ['payout.paid', 'payout.failed', 'payout.created'],
    url: 'https://example.com/new_endpoint',
  }
);
RESPONSE
{
  "id": "we_z_1Mr5jULkdIwHu7ix",
  "object": "webhook_endpoint",
  "api_version": null,
  "application": null,
  "created": 1704067200,
  "description": "Updated webhook for all payout events",
  "enabled_events": [
    "payout.paid",
    "payout.failed",
    "payout.created"
  ],
  "livemode": true,
  "metadata": {},
  "platform_account": "acct_z_Platform123abc",
  "status": "enabled",
  "url": "https://example.com/new_endpoint"
}

Retrieve a webhook endpoint

Retrieves the webhook endpoint with the given ID.

ENDPOINTS
GET /v1/webhook_endpoints/:id

Parameters

No parameters.

Returns

Returns a webhook endpoint if a valid webhook endpoint ID was provided. Raises an error otherwise.

GET/v1/webhook_endpoints/:id
import { Zoneless } from '@zoneless/node';
const zoneless = new Zoneless('sk_live_z_YOUR_API_KEY', 'https://api.zoneless.com');

const webhookEndpoint = await zoneless.webhookEndpoints.retrieve(
  'we_z_1Mr5jULkdIwHu7ix'
);
RESPONSE
{
  "id": "we_z_1Mr5jULkdIwHu7ix",
  "object": "webhook_endpoint",
  "api_version": null,
  "application": null,
  "created": 1704067200,
  "description": "Webhook for payout notifications",
  "enabled_events": [
    "payout.paid",
    "payout.failed"
  ],
  "livemode": true,
  "metadata": {},
  "platform_account": "acct_z_Platform123abc",
  "status": "enabled",
  "url": "https://example.com/my/webhook/endpoint"
}

List all webhook endpoints

Returns a list of your webhook endpoints.

ENDPOINTS
GET /v1/webhook_endpoints

Parameters

No required parameters.

More attributes

Returns

A dictionary with a data property that contains an array of up to limit webhook endpoints, starting after webhook endpoint starting_after. Each entry in the array is a separate Webhook Endpoint object. If no more webhook endpoints are available, the resulting array is empty. This request should never raise an error.

GET/v1/webhook_endpoints
import { Zoneless } from '@zoneless/node';
const zoneless = new Zoneless('sk_live_z_YOUR_API_KEY', 'https://api.zoneless.com');

const webhookEndpoints = await zoneless.webhookEndpoints.list({
  limit: 3,
});
RESPONSE
{
  "object": "list",
  "url": "/v1/webhook_endpoints",
  "has_more": false,
  "data": [
    {
      "id": "we_z_1Mr5jULkdIwHu7ix",
      "object": "webhook_endpoint",
      "api_version": null,
      "application": null,
      "created": 1704067200,
      "description": "Webhook for payout notifications",
      "enabled_events": [
        "payout.paid",
        "payout.failed"
      ],
      "livemode": true,
      "metadata": {},
      "platform_account": "acct_z_Platform123abc",
      "status": "enabled",
      "url": "https://example.com/my/webhook/endpoint"
    }
  ]
}

Delete a webhook endpoint

Deletes a webhook endpoint. Once deleted, the endpoint will no longer receive any events.

ENDPOINTS
DELETE /v1/webhook_endpoints/:id

Parameters

No parameters.

Returns

An object with the deleted webhook endpoint's ID. Otherwise, this call raises an error, such as if the webhook endpoint has already been deleted.

DELETE/v1/webhook_endpoints/:id
import { Zoneless } from '@zoneless/node';
const zoneless = new Zoneless('sk_live_z_YOUR_API_KEY', 'https://api.zoneless.com');

const deleted = await zoneless.webhookEndpoints.del(
  'we_z_1Mr5jULkdIwHu7ix'
);
RESPONSE
{
  "id": "we_z_1Mr5jULkdIwHu7ix",
  "object": "webhook_endpoint",
  "deleted": true
}