Help — Getting started with webhooks

Getting started

Webhooks are set up from Community Settings → Webhooks. An admin needs the webhooks.edit permission to add or change the URL. Once added, you'll be shown a Client ID and Client Secret — the secret is shown once, so store it in your secret manager before closing.

Open Community Settings → Webhooks.

Paste your endpoint URL (HTTPS only).

Copy the Client ID and Secret. The secret cannot be retrieved later.

Verify your endpoint with the call below — this confirms the connection.

Optionally Send test event to dry-run your handler.

Verifying your endpoint

cURL

curl -X POST https://api.key.community/v1/webhooks/verify \
  -H "Content-Type: application/json" \
  -H "X-Client-Id: $KEY_WEBHOOK_CLIENT_ID" \
  -d '{
    "communityId": "a9e2f12c-7c8d-4b3f-b9c1-2d6e3f5a8b10",
    "clientId":    "wh_8aF3kL2pNxRqYv9c",
    "clientSecret":"sk_3xZqW2tBnMv8KpYjL5hVcG1Rd"
  }'

# → 200 OK
# { "message": "Webhook endpoint verified successfully." }

Node.js

import { request } from 'undici';

const { body } = await request('https://api.key.community/v1/webhooks/verify', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Client-Id':  process.env.KEY_WEBHOOK_CLIENT_ID,
  },
  body: JSON.stringify({
    communityId:  process.env.KEY_COMMUNITY_ID,
    clientId:     process.env.KEY_WEBHOOK_CLIENT_ID,
    clientSecret: process.env.KEY_WEBHOOK_SECRET,
  }),
});

console.log(await body.json());
// { message: 'Webhook endpoint verified successfully.' }

Python

import os, requests

resp = requests.post(
    "https://api.key.community/v1/webhooks/verify",
    headers={"X-Client-Id": os.environ["KEY_WEBHOOK_CLIENT_ID"]},
    json={
        "communityId":  os.environ["KEY_COMMUNITY_ID"],
        "clientId":     os.environ["KEY_WEBHOOK_CLIENT_ID"],
        "clientSecret": os.environ["KEY_WEBHOOK_SECRET"],
    },
)
print(resp.json())
# {'message': 'Webhook endpoint verified successfully.'}