Call createWebhookSubscription with an HTTPS URL, eventTypes: ["*"], and an idempotency key (IK). The authenticated API client determines the workspace.

mutation CreateWebhookSubscription($ik: SafeString!, $input: CreateWebhookSubscriptionInput!) {
  createWebhookSubscription(ik: $ik, input: $input) {
    __typename
    ... on CreateWebhookSubscriptionResult {
      subscription { id webhookVersion }
      signingSecret
    }
    ... on Error { code message retryable }
  }
}

The following subscription receives all event types from every Ledger in its workspace.

{
  "ik": "payment-events-webhook",
  "input": {
    "url": "https://example.com/webhooks/fragment",
    "eventTypes": ["*"]
  }
}

Save signingSecret securely on your backend. The API returns it only when the subscription is first created.

On success, the mutation returns:

Creation retries

Follow the API's idempotency rules, with these webhook-specific differences:

• Creation keys belong to the workspace.
• Reusing a key with a different URL or webhook version returns BadRequestError.
• Successful retries return the existing subscription with isIkReplay: true and signingSecret: null.
• Deleted subscriptions keep their creation keys reserved. Reusing those keys returns BadRequestError.

Call webhookSubscriptions to list active subscriptions in the authenticated workspace. Deleted subscriptions are excluded.

query ListWebhookSubscriptions($first: Int, $after: String) {
  webhookSubscriptions(first: $first, after: $after) {
    nodes {
      id
      url
      eventTypes
      webhookVersion
      created
    }
    pageInfo { endCursor hasNextPage hasPreviousPage startCursor }
  }
}

Pass endCursor as after while hasNextPage is true. Each node has the fields below.

Call deleteWebhookSubscription with the subscription ID. Repeating deletion returns success: true.

mutation DeleteWebhookSubscription($id: ID!) {
  deleteWebhookSubscription(id: $id) {
    __typename
    ... on DeleteWebhookSubscriptionResult { success }
    ... on Error { code message retryable }
  }
}

Deletion stops queued deliveries and future retries. A request already in flight may finish.

• The creation IK stays reserved: reusing it returns BadRequestError, so creating another subscription requires a new IK.

On success, the mutation returns: