Pre-release — content may change.

GuidesWebhooks

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

  1. 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
  2. Wicket sends a test payload to verify your endpoint is reachable

  3. 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
  4. Verify the signature to ensure the request came from Wicket

  5. 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 updated
  • people.address_changed - Address added/updated
  • people.email_changed - Email added/updated
  • people.phone_changed - Phone added/updated
  • people.web_address_changed - Web address added/updated

Organization Events

  • organizations.changed - Organization record updated
  • organizations.address_changed - Address added/updated
  • organizations.email_changed - Email added/updated
  • organizations.phone_changed - Phone added/updated
  • organizations.web_address_changed - Web address added/updated

Role Events

  • roles.granted - Role assigned to a user
  • roles.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 webhook
  • webhook_bundle_uuid: Unique identifier for this delivery
  • events: Array of one or more events
  • test: true for test payloads, false for real events

Security Headers

Each webhook request includes security headers:

  • X-WicketEvents-Signature: HMAC-SHA256 signature for verification
  • X-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:

  1. Go to webhook.site and copy your unique URL
  2. Create a webhook endpoint with that URL
  3. Trigger events in Wicket
  4. 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/wicket

Troubleshooting

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 active not inactive
  • Review webhook endpoint configuration via GET /webhook/endpoints

On this page