Skip to content

Clarify webhook SDK compatibility docs #697

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
grahamritter merged 2 commits into from
Jun 8, 2026
Merged

Clarify webhook SDK compatibility docs #697

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
fd7e1ef
Clarify webhook SDK compatibility docs
taylorjdawson Jun 5, 2026
98e05b7
Tighten webhook SDK wording
taylorjdawson Jun 5, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 13 additions & 5 deletions features/webhooks/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,14 @@ Create webhook endpoints from a server-side client using an API key, or from any

SDK methods accept the intent parameters directly. The SDK adds the activity envelope fields (`type`, `timestampMs`, `organizationId`, and `parameters`) before signing and submitting the request. Use the raw envelope shape only when calling the HTTP API directly.

<Note>
For server-side/API-key automation, use `@turnkey/sdk-server@6.1.0+`; it includes `createWebhookEndpoint`.

For browser clients that can submit signed activities for the organization, `@turnkey/sdk-browser@6.1.0+` also includes `createWebhookEndpoint`.

Raw HTTP and CLI submission remain supported for direct activity submission. SDK methods accept intent parameters directly; raw HTTP uses the activity envelope shape.
</Note>

### Activity updates

```ts
Expand Down Expand Up @@ -236,9 +244,9 @@ Read operations, such as listing webhook endpoints, use standard authenticated q

| Symptom | What to check |
|---|---|
| `createWebhookEndpoint` is unavailable in your SDK | Upgrade to a webhooks-capable SDK release. The minimum SDK version will be listed in the SDK changelog once published. |
| `PermissionDenied` on create/update/delete | Confirm the user has an allow policy for the webhook activity type, and confirm balance webhooks are being managed from the billing organization. |
| Empty or unclear endpoint names | Set `parameters.name` to a non-empty, human-readable name. |
| Subscription shape errors | Pass event types inside `parameters.subscriptions[]`, not as top-level `eventTypes`. |
| `createWebhookEndpoint` is unavailable in your SDK | Upgrade to `@turnkey/sdk-server@6.1.0+` or `@turnkey/sdk-browser@6.1.0+`. Use `@turnkey/sdk-server` for server-side/API-key automation. Use `@turnkey/sdk-browser` only when the browser client can submit signed activities for the organization. |
| `PermissionDenied` on create/update/delete | Confirm the user has an allow policy for the webhook activity type. For balance or transaction-status webhooks, also confirm the endpoint is being managed from the billing organization. |
| Subscription shape errors | Pass event types inside `subscriptions[]`, not as top-level `eventTypes`. For raw HTTP activity submission, put `subscriptions[]` inside `parameters`. |
| Empty endpoint names | Set a non-empty, human-readable `name`. For raw HTTP activity submission, set `parameters.name`. |
| Invalid webhook URL errors | Use an HTTPS URL that resolves to a public destination. Localhost, private IPs, link-local addresses, metadata endpoints, and URLs with user info are rejected. |
| Signature verification fails | See [Verify webhook signatures](/features/webhooks/verify-signatures). Common causes: re-serialized JSON body, clock skew, or missing signing key. |
| Signature verification fails | See [Verify webhook signatures](/features/webhooks/verify-signatures). Common causes: not using the exact raw request body, clock skew, or a missing/stale JWKS key. Cache JWKS according to `Cache-Control` and refetch when the signature `kid` is unknown. |