Overview
Receive real-time notifications about data changes in Wicket
Webhooks allow you to receive real-time notifications when data changes in your Wicket account. Instead of polling the API for updates, Wicket will send HTTP POST requests to your server when events occur.
What are Webhooks?
Webhooks are HTTP POST requests sent to a URL you specify (your "endpoint") when certain events occur in Wicket. This allows you to:
- Sync data in real-time instead of polling
- Trigger workflows when data changes
- Keep external systems updated automatically
- Reduce API calls and stay within rate limits
How Webhooks Work
-
Create a webhook endpoint via the API, specifying:
- Your target URL to receive webhook POSTs
- Which events you want to subscribe to
- A name for the endpoint
-
Wicket sends a test payload to verify your endpoint is reachable
-
Receive webhook POST requests when subscribed events occur:
- Each request includes event data and a security signature
- Events are bundled together when multiple changes occur simultaneously
- Retries are attempted if your endpoint doesn't respond successfully
-
Verify the signature to ensure the request came from Wicket
-
Process the event data and respond with a 2xx status code
Quick Start
Create an endpoint
Set up your webhook endpoint to start receiving events.
Setup Guide
Subscribe to events
Choose which events you want to receive notifications for.
Event Catalog
Verify signatures
Implement HMAC-SHA256 verification for security.
Security Guide
Available Events
Wicket supports webhooks for these event types:
People Events
people.changed- Person record updatedpeople.address_changed- Address added/updatedpeople.email_changed- Email added/updatedpeople.phone_changed- Phone added/updatedpeople.web_address_changed- Web address added/updated
Organization Events
organizations.changed- Organization record updatedorganizations.address_changed- Address added/updatedorganizations.email_changed- Email added/updatedorganizations.phone_changed- Phone added/updatedorganizations.web_address_changed- Web address added/updated
Role Events
roles.granted- Role assigned to a userroles.revoked- Role removed from a user
See the Event Catalog for detailed descriptions and payload examples.
Webhook Payload Structure
All webhook requests follow this structure:
{
"webhook_delivery_timestamp": "2023-06-20T18:10:20.183Z",
"webhook_bundle_uuid": "be14b026-a972-4a69-bdc2-b58ce8c2d2c0",
"events": [
{
"id": "a5b33199-9dd3-4552-8c47-028f6c32ef48",
"type": "person_webhook_summary",
"event_type": "people.changed",
"event_id": "6d2b7371-36b9-4060-b6ca-ddafda50541d",
"event_timestamp": "2023-06-21T16:53:43.604Z",
"attributes": {
"uuid": "a5b33199-9dd3-4552-8c47-028f6c32ef48",
"given_name": "John",
"family_name": "Smith",
"primary_email_address": "john@mail.com",
"updated_at": "2023-06-21T16:53:43.600Z"
}
}
],
"test": false
}Key fields:
webhook_delivery_timestamp: When Wicket sent the webhookwebhook_bundle_uuid: Unique identifier for this deliveryevents: Array of one or more eventstest:truefor test payloads,falsefor real events
Security Headers
Each webhook request includes security headers:
X-WicketEvents-Signature: HMAC-SHA256 signature for verificationX-WicketEvents-Host: Originating Wicket host
Always verify the signature before processing webhook data. See the Security Guide for implementation details.
Best Practices
1. Respond Quickly
Respond with a 2xx status code as soon as you receive the webhook:
app.post('/webhooks/wicket', (req, res) => {
// Immediately acknowledge receipt
res.status(200).send('OK');
// Process asynchronously
processWebhookAsync(req.body);
});2. Verify Signatures
Always verify the HMAC-SHA256 signature:
const crypto = require('crypto');
function verifyWebhook(signatureKey, body, signature) {
const expectedSignature = crypto
.createHmac('sha256', signatureKey)
.update(body)
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expectedSignature)
);
}3. Handle Test Payloads
Skip verification for test payloads (sent when creating endpoints):
if (payload.test === true) {
// This is a test payload - skip signature verification
return res.status(200).send('Test payload received');
}4. Handle Event Bundles
Multiple events may be bundled together:
for (const event of payload.events) {
switch (event.event_type) {
case 'people.changed':
handlePersonChanged(event);
break;
case 'people.email_changed':
handleEmailChanged(event);
break;
// ... handle other event types
}
}5. Implement Idempotency
Use event_id to prevent duplicate processing:
const processedEvents = new Set();
function processEvent(event) {
if (processedEvents.has(event.event_id)) {
console.log('Event already processed:', event.event_id);
return;
}
// Process the event
// ...
processedEvents.add(event.event_id);
}6. Monitor and Log
Log webhook deliveries for debugging:
console.log('Webhook received:', {
bundle_uuid: payload.webhook_bundle_uuid,
event_count: payload.events.length,
timestamp: payload.webhook_delivery_timestamp
});Testing Webhooks
Using webhook.site
During development, use a service like webhook.site to inspect webhook payloads:
- Go to webhook.site and copy your unique URL
- Create a webhook endpoint with that URL
- Trigger events in Wicket
- View the payloads in webhook.site
Local Testing with ngrok
Test locally using ngrok:
# Start your local server on port 3000
npm start
# In another terminal, start ngrok
ngrok http 3000
# Use the ngrok URL for your webhook endpoint
# Example: https://abc123.ngrok.io/webhooks/wicketTroubleshooting
Webhook Not Received
- Verify your endpoint is publicly accessible
- Check firewall rules allow incoming POST requests
- Ensure your endpoint responds with 2xx status codes
- Review webhook endpoint status (active vs inactive)
Signature Verification Failing
- Verify you're using the correct
signature_key(saved from webhook creation) - Ensure you're hashing the raw request body, not parsed JSON
- Check you're using HMAC-SHA256 algorithm
- Confirm signature comparison is timing-safe
Events Missing
- Verify you subscribed to the correct event types
- Check webhook endpoint is
activenotinactive - Review webhook endpoint configuration via GET
/webhook/endpoints