Webhook Configuration¶

Endpoint	Method	Scope	Token Tier	Description
`/api/v1/webhook-configuration/`	GET	`webhooks:read`	Both	Read your webhook destination and events
`/api/v1/webhook-configuration/`	PATCH	`webhooks:write`	Application-level	Change your destination or events

Try it out

Explore parameters, schemas, and live requests in the Swagger UI.

This endpoint is how you configure webhook delivery for your own application: where deliveries go, and which event types you want. It is a singleton — your application has exactly one webhook configuration, and there is no id in the URL because the subject is derived from your token.

For what each event contains, see Webhooks. To read back what was already delivered, see Webhook Events.

webhooks:write is application-level

This configuration applies to every user your application serves, so it can only be changed with an application-level token. A user-scoped token can read the configuration but cannot be issued the webhooks:write scope at all. Ask Beyond to enable webhooks:write for your application if it is not in your allowed scopes.

Read Your Configuration¶

GET /api/v1/webhook-configuration/

{
  "data": {
    "type": "webhook-configurations",
    "id": "your-client-id",
    "attributes": {
      "webhook-url": "https://example.com/beyond/webhooks",
      "subscribed-events": ["*"],
      "available-events": [
        "account.created",
        "account.refreshed",
        "listing.base_price_changed",
        "listing.created",
        "listing.in_active_market_changed",
        "listing.refreshed"
      ]
    }
  }
}

Attribute	Description
`id`	Your application's client id.
`webhook-url`	Where deliveries are sent. Empty means delivery is off.
`subscribed-events`	The event types you receive. `["*"]` means every type — see below.
`available-events`	Every event type you may subscribe to (read-only).

Your signing secret is never returned here, or anywhere else in the API. It is shown once when it is issued or rotated.

Choosing Your Events¶

subscribed-events is returned exactly as stored, and ["*"] is meaningful in its own right:

Value	Meaning
`["*"]`	Every event type, including ones Beyond adds in future. This is the default.
`["listing.created", "account.refreshed"]`	Exactly these types. New event types are not delivered until you add them here.
`[]`	No events at all. Delivery is effectively off while your URL stays configured.

Pick ["*"] if you want everything and would rather opt out later; pick an explicit list if your receiver rejects or mishandles payloads it does not recognize. ["*"] combined with concrete types is stored as ["*"] — the wildcard always wins, so you cannot accidentally narrow yourself while it is set.

PATCH /api/v1/webhook-configuration/
Content-Type: application/vnd.api+json

{
  "data": {
    "type": "webhook-configurations",
    "id": "your-client-id",
    "attributes": {
      "subscribed-events": ["listing.created", "listing.base_price_changed"]
    }
  }
}

Every attribute you send replaces the stored value — subscribed-events is not merged, so send the complete list you want rather than the additions. Omit an attribute to leave it untouched. An event type that is not in available-events returns 400, naming both the value and the valid list.

Every update must carry data.id, your own client id — the same value GET returns. JSON:API requires it on an update, so a request without it returns 400, and one naming a different application returns 409.

Changing Your Destination URL¶

{
  "data": {
    "type": "webhook-configurations",
    "id": "your-client-id",
    "attributes": {
      "webhook-url": "https://example.com/beyond/webhooks-v2"
    }
  }
}

The new URL takes effect immediately. Beyond does not probe it first, so make sure it is live and verifying signatures before you switch — and note that deliveries already in flight, including retries of earlier events, may still land on the previous URL for a short period. Run both endpoints in parallel over a cutover if you cannot tolerate that.

The URL must:

use https;
point at a publicly reachable host — localhost, loopback, link-local (169.254.0.0/16), and private literals (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16) are rejected with 400.

Send "" to switch delivery off without losing your event selection; null is accepted and read back as "". Turning delivery back on is the same request with a URL again.

Changing this redirects your signed event stream

A token holding webhooks:write can point your event stream at any public HTTPS endpoint. Treat it with the same care as any other credential that can move data, and grant it only to systems that need to configure webhooks.

Rotating the Signing Secret¶

Not yet available through the API. Contact Beyond to rotate it — see Rotation in the webhooks guide for what a rotation involves today.

Errors¶

Status	Cause
`400`	An event type not in `available-events`, a missing `data.id`, or a `webhook-url` that is not public HTTPS.
`401`	Missing or invalid bearer token.
`403`	Token lacks `webhooks:read` (GET) or `webhooks:write` (PATCH — application-level tokens only).
`409`	`data.id` names a different application than the one your token authenticates.
`429`	Rate limit exceeded — this endpoint is capped at 30 requests/minute. See Rate Limiting.