Subscriptions

A subscription records where your events go and which ones you want. Every endpoint on this page requires the webhooks permission and is scoped to your partner account.

The signing secret is returned on exactly two endpoints — create and rotate — and only once each. Store it when you receive it.

The subscription object

uuid

Subscription id.

enum

PUSH (default) or PULL. See delivery modes.

string | null

Your HTTPS receiver URL. Present for PUSH, null for PULL.

string[]

The types you receive. ["*"] means all of them.

string

Version of the delivered payload. Defaults to "1.0".

enum

ACTIVE, PAUSED, SUSPENDED, or DELETED.

string

A non-sensitive fingerprint of the signing secret.

string

The plaintext signing secret. Returned only on create and rotate.

date-time

When the subscription was created.

Create a subscription

Registers a subscription — PUSH by default, or PULL — and returns your signing secret once.

Body

enum

default:"PUSH"

PUSH or PULL. See delivery modes.

string

required

Required for PUSH; ignored for PULL, where it is stored as null. Must be an absolute https:// URL on a public host, using an allowed port, with no embedded credentials. Maximum 512 characters.

string[]

default:"[\"*\"]"

The event types to receive.

string

default:"1.0"

Payload version to deliver.

curl -X POST https://qa-api.endl.xyz/api/v0/webhooks/subscriptions \
  -H "X-API-KEY: $ENDL_API_KEY" -H "X-API-SECRET: $ENDL_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "target": "https://api.acme.com/webhooks/endl",
    "eventFilter": ["payout.completed", "payout.failed"]
  }'

{
  "code": 201,
  "message": "Subscription created",
  "status": "SUCCESS",
  "data": {
    "id": "2b1e8f40-3c9a-4d21-9f7e-6a1c0b5d2e34",
    "deliveryMode": "PUSH",
    "target": "https://api.acme.com/webhooks/endl",
    "eventFilter": ["payout.completed", "payout.failed"],
    "schemaVersion": "1.0",
    "status": "ACTIVE",
    "secretHint": "whsec_…5RtBw",
    "webhook_secret": "whsec_k2p9Fa7QxVn3Jh05RtBw",
    "createdOn": "2026-09-02T12:34:56.789Z"
  },
  "errors": []
}

Store the secret now. webhook_secret is shown only in this response. If you lose it, your only option is to rotate.

Create a PULL subscription

Omit target and set "deliveryMode": "PULL". A PULL subscription never delivers anything — it authorizes and configures the event feed, carrying the eventFilter and schemaVersion that feed reads. You may have one live PULL subscription per partner, and it requires the events permission. A signing secret is still returned: PULL responses are unsigned, but rotation and the secret hint stay consistent across both modes.

curl -X POST https://qa-api.endl.xyz/api/v0/webhooks/subscriptions \
  -H "X-API-KEY: $ENDL_API_KEY" -H "X-API-SECRET: $ENDL_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "deliveryMode": "PULL",
    "eventFilter": ["payout.completed", "payout.failed"]
  }'

{
  "code": 201,
  "message": "Subscription created",
  "status": "SUCCESS",
  "data": {
    "id": "7d3a1c22-88fe-4b90-a1c4-2f0e9b6d5a10",
    "deliveryMode": "PULL",
    "target": null,
    "eventFilter": ["payout.completed", "payout.failed"],
    "schemaVersion": "1.0",
    "status": "ACTIVE",
    "secretHint": "whsec_…9QsLm",
    "webhook_secret": "whsec_Xr4Tn8Va2Kd7Bp19QsLm",
    "createdOn": "2026-09-02T12:34:56.789Z"
  },
  "errors": []
}

Status codes

201 created · 400 invalid or blocked target, target missing for PUSH, or missing permission · 409 duplicate target, active cap of 5 reached, or a live PULL subscription already exists · 422 SQS or SSE requested · 401 / 503 authentication

List subscriptions

Returns all your non-deleted subscriptions, newest first, as data.subscriptions[] with data.totalCount. Never includes webhook_secret. There is no pagination — you get everything.

curl https://qa-api.endl.xyz/api/v0/webhooks/subscriptions \
  -H "X-API-KEY: $ENDL_API_KEY" -H "X-API-SECRET: $ENDL_API_SECRET"

{
  "code": 200,
  "message": "Success",
  "status": "SUCCESS",
  "data": {
    "subscriptions": [
      {
        "id": "2b1e8f40-3c9a-4d21-9f7e-6a1c0b5d2e34",
        "deliveryMode": "PUSH",
        "target": "https://api.acme.com/webhooks/endl",
        "eventFilter": ["payout.completed", "payout.failed"],
        "schemaVersion": "1.0",
        "status": "ACTIVE",
        "secretHint": "whsec_…5RtBw",
        "createdOn": "2026-09-02T12:34:56.789Z"
      }
    ],
    "totalCount": 1
  },
  "errors": []
}

Status codes

200 · 400 missing permission · 401 / 503 authentication

Get a subscription

Fetches one subscription by its UUID.

curl https://qa-api.endl.xyz/api/v0/webhooks/subscriptions/2b1e8f40-3c9a-4d21-9f7e-6a1c0b5d2e34 \
  -H "X-API-KEY: $ENDL_API_KEY" -H "X-API-SECRET: $ENDL_API_SECRET"

{
  "code": 200,
  "message": "Success",
  "status": "SUCCESS",
  "data": {
    "id": "2b1e8f40-3c9a-4d21-9f7e-6a1c0b5d2e34",
    "deliveryMode": "PUSH",
    "target": "https://api.acme.com/webhooks/endl",
    "eventFilter": ["payout.completed", "payout.failed"],
    "schemaVersion": "1.0",
    "status": "ACTIVE",
    "secretHint": "whsec_…5RtBw",
    "createdOn": "2026-09-02T12:34:56.789Z"
  },
  "errors": []
}

Status codes

200 · 404 not found, not yours, or deleted · 400 non-UUID id or missing permission · 401 / 503 authentication

Update a subscription

A partial update: a null or omitted field is left unchanged. You can change the status and the event filter.

Body

enum

PAUSED holds events, ACTIVE resumes delivery, DELETED soft-deletes. SUSPENDED is rejected with a 400 — only Endl sets it.

string[]

Replaces the current filter. An empty list resets it to ["*"].

The target URL is immutable. A request that includes target is rejected. To send events somewhere else, delete the subscription and create a new one, which issues a fresh signing secret. This is deliberate: it stops a compromised key from silently repointing a live, signed event stream at an attacker.

curl -X PATCH https://qa-api.endl.xyz/api/v0/webhooks/subscriptions/2b1e8f40-3c9a-4d21-9f7e-6a1c0b5d2e34 \
  -H "X-API-KEY: $ENDL_API_KEY" -H "X-API-SECRET: $ENDL_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "status": "PAUSED", "eventFilter": ["payout.completed"] }'

{
  "code": 200,
  "message": "Subscription updated",
  "status": "SUCCESS",
  "data": {
    "id": "2b1e8f40-3c9a-4d21-9f7e-6a1c0b5d2e34",
    "deliveryMode": "PUSH",
    "target": "https://api.acme.com/webhooks/endl",
    "eventFilter": ["payout.completed"],
    "schemaVersion": "1.0",
    "status": "PAUSED",
    "secretHint": "whsec_…5RtBw",
    "createdOn": "2026-09-02T12:34:56.789Z"
  },
  "errors": []
}

Status codes

200 · 400 SUSPENDED requested, target supplied, or missing permission · 404 not found · 409 resuming would exceed the active cap · 401 / 503 authentication

Rotate the signing secret

Issues a new signing secret and returns it once. This is the only endpoint besides create that returns webhook_secret.

Endl signs with the new secret immediately — there is no overlap window. Accept both the old and the new secret in your verifier until every instance has rolled over. See replay and rotation.

curl -X POST https://qa-api.endl.xyz/api/v0/webhooks/subscriptions/2b1e8f40-3c9a-4d21-9f7e-6a1c0b5d2e34/rotate-secret \
  -H "X-API-KEY: $ENDL_API_KEY" -H "X-API-SECRET: $ENDL_API_SECRET"

{
  "code": 200,
  "message": "Signing secret rotated",
  "status": "SUCCESS",
  "data": {
    "id": "2b1e8f40-3c9a-4d21-9f7e-6a1c0b5d2e34",
    "deliveryMode": "PUSH",
    "target": "https://api.acme.com/webhooks/endl",
    "eventFilter": ["payout.completed"],
    "schemaVersion": "1.0",
    "status": "ACTIVE",
    "secretHint": "whsec_…9Kd2",
    "webhook_secret": "whsec_NEWvalueStoreThisNow",
    "createdOn": "2026-09-02T12:34:56.789Z"
  },
  "errors": []
}

Status codes

200 rotated · 404 not found · 400 missing permission · 401 / 503 authentication

Delete a subscription

Soft-deletes the subscription. It returns 200 with status: "DELETED", not an empty 204. In-flight deliveries are cancelled, delivery history is kept, and the URL can be registered again later.

curl -X DELETE https://qa-api.endl.xyz/api/v0/webhooks/subscriptions/2b1e8f40-3c9a-4d21-9f7e-6a1c0b5d2e34 \
  -H "X-API-KEY: $ENDL_API_KEY" -H "X-API-SECRET: $ENDL_API_SECRET"

{
  "code": 200,
  "message": "Subscription deleted",
  "status": "SUCCESS",
  "data": {
    "id": "2b1e8f40-3c9a-4d21-9f7e-6a1c0b5d2e34",
    "deliveryMode": "PUSH",
    "target": "https://api.acme.com/webhooks/endl",
    "eventFilter": ["payout.completed"],
    "schemaVersion": "1.0",
    "status": "DELETED",
    "secretHint": "whsec_…9Kd2",
    "createdOn": "2026-09-02T12:34:56.789Z"
  },
  "errors": []
}

Status codes

200 · 404 not found or already deleted · 400 missing permission · 401 / 503 authentication

Send an event to a subscription

Manually sends an already-recorded event to this subscription. This is useful for a subscription that did not exist when the event first occurred. It queues a delivery rather than sending synchronously, and returns a deliveryId you can follow in Deliveries.

Body

string

required

The event id — the value delivered as X-WEBHOOK-EVENT-ID. Maximum 64 characters.

curl -X POST https://qa-api.endl.xyz/api/v0/webhooks/subscriptions/2b1e8f40-3c9a-4d21-9f7e-6a1c0b5d2e34/send \
  -H "X-API-KEY: $ENDL_API_KEY" -H "X-API-SECRET: $ENDL_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "eventId": "evt_9f1a4c7b2e08" }'

{
  "code": 200,
  "message": "Event queued for delivery",
  "status": "SUCCESS",
  "data": {
    "message": "queued for delivery — this does not guarantee immediate receipt at the endpoint",
    "deliveryId": "4d2f6a11-8c73-4b90-9e21-5f0a2c8d1e44"
  },
  "errors": []
}

A 200 here means the delivery was queued, not received. Track the returned deliveryId to find out what actually happened.

Status codes

200 queued · 400 bad eventId, a PULL subscription, a send rate limit, or missing permission · 404 subscription or event not found · 409 conflicting delivery · 401 / 503 authentication

Get started

Endpoints

Conventions

The subscription object

Create a subscription

Body

Create a PULL subscription

List subscriptions

Get a subscription

Update a subscription

Body

Rotate the signing secret

Delete a subscription

Send an event to a subscription

Body

​The subscription object

​Create a subscription

​Body

​Create a PULL subscription

​List subscriptions

​Get a subscription

​Update a subscription

​Body

​Rotate the signing secret

​Delete a subscription

​Send an event to a subscription

​Body

The subscription object

Create a subscription

Body

Create a PULL subscription

List subscriptions

Get a subscription

Update a subscription

Body

Rotate the signing secret

Delete a subscription

Send an event to a subscription

Body