Add Webhooks V2 documentation#651
Open
taylorjdawson wants to merge 2 commits intomainfrom
Open
Conversation
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
taylorjdawson
force-pushed
the
taylor/eng-4112-webhooks-v2-docs
branch
from
cd7d9cd to
af8a4e1
Compare
taylorjdawson
force-pushed
the
taylor/eng-4112-webhooks-v2-docs
branch
from
af8a4e1 to
f816157
Compare
…n webhooks.mdx Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
grahamritter
reviewed
May 7, 2026
| title: "Activity webhooks" | ||
| description: "Webhooks provide a powerful mechanism to receive notifications about activity requests in your Turnkey organization. Additionally, you'll be able to receive all activity requests for both the parent organization and all its child organizations. This functionality can be enabled via the organization feature capabilities of our platform, as detailed in the section on [organization features](/concepts/organizations#features)." | ||
| title: "Webhooks" | ||
| description: "Use Webhooks V2 to receive signed notifications for activity and balance events in your Turnkey organization." |
grahamritter
reviewed
May 7, 2026
| --- | ||
|
|
||
| This guide is designed to walk you through the process of setting up webhooks, from environment preparation to verification of successful event capturing. | ||
| Webhooks V2 sends HTTPS `POST` requests to endpoints that you register with Turnkey. Each endpoint can subscribe to one or more event types, and every delivery includes Turnkey headers. Signed deliveries also include Ed25519 signature headers so your receiver can verify that the request came from Turnkey before processing it. |
There was a problem hiding this comment.
Can we remove V2 from here and throughout?
grahamritter
reviewed
May 7, 2026
|
|
||
| ## Prerequisites | ||
| <Info> | ||
| Webhooks V2 is the recommended integration path for new webhook integrations. Legacy activity webhooks configured with `FEATURE_NAME_WEBHOOK` are still described at the end of this page for existing integrations. |
There was a problem hiding this comment.
I'd say we just remove this all-together - we are requiring a full-on migration anyways - any slow movers we can work with 1:1
grahamritter
reviewed
May 7, 2026
| | Event type | Description | Configuration scope | | ||
| | --- | --- | --- | | ||
| | `ACTIVITY_UPDATES` | Sends activity status updates. Parent-owned subscriptions receive parent and sub-organization activity events. Sub-organization-owned subscriptions receive only that sub-organization's activity events. | Organization-scoped | | ||
| | `BALANCE_CONFIRMED_UPDATES` | Sends confirmed balance update events for tracked wallet account addresses. | Billing organization / parent organization scoped | |
There was a problem hiding this comment.
would suggest below this a tip on viewing the balances documentation as there are tier implications. (https://docs.turnkey.com/concepts/balances#balances)
suggested language: "For further information on balances please see (https://docs.turnkey.com/concepts/balances#balances)"
grahamritter
reviewed
May 7, 2026
| | List endpoints | [`/public/v1/query/list_webhook_endpoints`](/api-reference/queries/list-webhook-endpoints) | Returns endpoints and their subscriptions for an organization. | | ||
|
|
||
| Set `isActive` to `false` if you want to pause delivery without deleting the endpoint. | ||
|
|
There was a problem hiding this comment.
Also add: "You can also manage webhooks via the Dashboard UI."
grahamritter
reviewed
May 7, 2026
| | Signature verification fails | Verify against the exact raw request body bytes, use the millisecond timestamp and event id from the headers, check clock skew, and select the public key matching the signature key id. | | ||
|
|
||
| Set your webhook URL using the Turnkey CLI with the following command: | ||
| ## Legacy activity webhooks |
There was a problem hiding this comment.
think we can cut this whole section
grahamritter
reviewed
May 7, 2026
| | `X-Turnkey-Webhook-Version` | Webhook delivery contract version. The current value is `1`. | | ||
|
|
||
| Here's an output of the above command: | ||
| Signed Webhooks V2 deliveries also include: |
There was a problem hiding this comment.
arent webhooks always going to be signed? I didnt think there was a configuration option here - would suggest collapsing the headers into one table!
grahamritter
reviewed
May 7, 2026
| </Info> | ||
|
|
||
| Before diving into webhook configuration, ensure you have completed the necessary preliminary steps outlined in our [Quickstart Guide](/getting-started/quickstart#create-your-turnkey-organization). This guide will assist you in setting up a new organization and installing the Turnkey CLI. Note: We'll create a new API Key for testing webhooks below. | ||
| ## Create an endpoint |
There was a problem hiding this comment.
Suggested Page order:
- Event types
- Create an endpoint
- Manage endpoints
- Delivery contract
- Verify signatures
- Payloads
- Permissions
- Troubleshooting
grahamritter
reviewed
May 7, 2026
| --- | ||
|
|
||
| This guide is designed to walk you through the process of setting up webhooks, from environment preparation to verification of successful event capturing. | ||
| Webhooks V2 sends HTTPS `POST` requests to endpoints that you register with Turnkey. Each endpoint can subscribe to one or more event types, and every delivery includes Turnkey headers. Signed deliveries also include Ed25519 signature headers so your receiver can verify that the request came from Turnkey before processing it. |
There was a problem hiding this comment.
suggest a new intro:
Webhooks let you receive real-time notifications from Turnkey as signed HTTPS POST requests. Register an endpoint, subscribe to event types, and Turnkey delivers activity and balance updates as they happen.
Key Capabilities:
- Signed deliveries with Ed25519 signatures and SDK verification helpers
- Organization-aware headers including org ID, event type, and timestamps on every delivery
- Automatic retries with backoff for failed deliveries (5xx and network errors)
- Dashboard and API management for creating and configuring endpoints
- Policy-engine permissioned through dedicated activity types, like any other Turnkey operation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Testing