Pre-release — content may change.

GuidesWebhooks

Webhook Setup

Creating and managing webhook endpoints

Learn how to create, configure, and manage webhook endpoints to receive real-time notifications from Wicket.

Creating a Webhook Endpoint

Request

POST /webhook/endpoints
Content-Type: application/vnd.api+json
Authorization: Bearer YOUR_JWT_TOKEN
{
  "data": {
    "type": "endpoints",
    "attributes": {
      "name": "Production Sync Endpoint",
      "target_url": "https://your-domain.com/webhooks/wicket",
      "status": "active",
      "events": [
        "people.changed",
        "people.email_changed",
        "organizations.changed"
      ]
    }
  }
}

Attributes:

FieldTypeRequiredDescription
namestringYesDescriptive name for the endpoint
target_urlstringYesHTTPS URL to receive webhook POSTs
statusstringYesactive or inactive
eventsarrayYesList of event types to subscribe to
filtersobjectNoJSON filter patterns keyed by event type. See the Event Filters section in the Webhooks introduction for syntax and examples.

Response

{
  "data": {
    "id": "endpoint-uuid",
    "type": "endpoints",
    "attributes": {
      "uuid": "endpoint-uuid",
      "name": "Production Sync Endpoint",
      "target_url": "https://your-domain.com/webhooks/wicket",
      "status": "active",
      "signature_key": "sk_live_abc123def456...",
      "signature_key_masked": "****456",
      "events": [
        "people.changed",
        "people.email_changed",
        "organizations.changed"
      ],
      "filters": {},
      "created_at": "2024-01-17T12:00:00.000Z",
      "updated_at": "2024-01-17T12:00:00.000Z"
    }
  }
}

Important: The signature_key is only returned once during creation. Store it securely! You'll need it to verify webhook signatures.

Test Payload

When you create a webhook endpoint, Wicket immediately sends a test payload to verify your endpoint is reachable:

{
  "webhook_delivery_timestamp": "2025-04-05T12:00:00Z",
  "webhook_bundle_uuid": null,
  "events": [],
  "test": true
}

Your endpoint should:

  1. Respond with a 2xx status code
  2. Skip signature verification when test: true (the signature_key isn't available yet)

Code Examples

const fetch = require('node-fetch');

async function createWebhookEndpoint() {
  const response = await fetch(
    `${apiUrl}/webhook/endpoints`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/vnd.api+json'
      },
      body: JSON.stringify({
        data: {
          type: 'endpoints',
          attributes: {
            name: 'Production Sync Endpoint',
            target_url: 'https://your-domain.com/webhooks/wicket',
            status: 'active',
            events: [
              'people.changed',
              'people.email_changed',
              'organizations.changed'
            ]
          }
        }
      })
    }
  );

  const data = await response.json();

  // IMPORTANT: Save the signature_key securely!
  const signatureKey = data.data.attributes.signature_key;
  console.log('Save this signature_key:', signatureKey);

  return data;
}
require 'net/http'
require 'json'

def create_webhook_endpoint
  uri = URI("#{api_url}/webhook/endpoints")
  request = Net::HTTP::Post.new(uri)
  request['Authorization'] = "Bearer #{token}"
  request['Content-Type'] = 'application/vnd.api+json'

  request.body = {
    data: {
      type: 'endpoints',
      attributes: {
        name: 'Production Sync Endpoint',
        target_url: 'https://your-domain.com/webhooks/wicket',
        status: 'active',
        events: [
          'people.changed',
          'people.email_changed',
          'organizations.changed'
        ]
      }
    }
  }.to_json

  response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
    http.request(request)
  end

  data = JSON.parse(response.body)

  # IMPORTANT: Save the signature_key securely!
  signature_key = data['data']['attributes']['signature_key']
  puts "Save this signature_key: #{signature_key}"

  data
end

Listing Webhook Endpoints

Request

GET /webhook/endpoints?page[number]=1&page[size]=25

Response

{
  "data": [
    {
      "id": "endpoint-uuid-1",
      "type": "endpoints",
      "attributes": {
        "uuid": "endpoint-uuid-1",
        "name": "Production Sync Endpoint",
        "target_url": "https://your-domain.com/webhooks/wicket",
        "status": "active",
        "signature_key_masked": "****456",
        "events": ["people.changed", "organizations.changed"],
        "created_at": "2024-01-17T12:00:00.000Z",
        "updated_at": "2024-01-17T12:00:00.000Z"
      }
    }
  ],
  "links": {
    "self": "/webhook/endpoints?page[number]=1&page[size]=25",
    "first": "/webhook/endpoints?page[number]=1&page[size]=25",
    "last": "/webhook/endpoints?page[number]=1&page[size]=25"
  }
}

Note that signature_key is not returned in list responses, only signature_key_masked for reference.

Fetching a Single Endpoint

Request

GET /webhook/endpoints/{endpoint_id}

Response

{
  "data": {
    "id": "endpoint-uuid",
    "type": "endpoints",
    "attributes": {
      "uuid": "endpoint-uuid",
      "name": "Production Sync Endpoint",
      "target_url": "https://your-domain.com/webhooks/wicket",
      "status": "active",
      "signature_key_masked": "****456",
      "events": ["people.changed"],
      "created_at": "2024-01-17T12:00:00.000Z",
      "updated_at": "2024-01-17T12:00:00.000Z"
    }
  }
}

Updating a Webhook Endpoint

You can update the name, target URL, status, or subscribed events.

Request

PATCH /webhook/endpoints/{endpoint_id}
Content-Type: application/vnd.api+json
{
  "data": {
    "id": "endpoint-uuid",
    "type": "endpoints",
    "attributes": {
      "status": "inactive",
      "events": [
        "people.changed",
        "people.email_changed",
        "people.phone_changed"
      ]
    }
  }
}

Response

Returns the updated endpoint resource (same format as creation response, but without signature_key).

Updating an endpoint does not regenerate the signature_key. The existing key remains valid.

Deleting a Webhook Endpoint

Request

DELETE /webhook/endpoints/{endpoint_id}

Response

204 No Content on successful deletion.

Managing Endpoint Status

Activating an Endpoint

PATCH /webhook/endpoints/{endpoint_id}
{
  "data": {
    "id": "endpoint-uuid",
    "type": "endpoints",
    "attributes": {
      "status": "active"
    }
  }
}

Deactivating an Endpoint

Temporarily disable webhooks without deleting the endpoint:

{
  "data": {
    "id": "endpoint-uuid",
    "type": "endpoints",
    "attributes": {
      "status": "inactive"
    }
  }
}

When inactive, no webhook POSTs will be sent to the endpoint.

Subscribing to Events

Adding Events

Update the events array to add new event types:

{
  "data": {
    "id": "endpoint-uuid",
    "type": "endpoints",
    "attributes": {
      "events": [
        "people.changed",
        "people.email_changed",
        "people.phone_changed",
        "people.address_changed"
      ]
    }
  }
}

Removing Events

Omit events you no longer want to receive:

{
  "data": {
    "id": "endpoint-uuid",
    "type": "endpoints",
    "attributes": {
      "events": [
        "people.changed"
      ]
    }
  }
}

When updating events, provide the complete list. Any events not included will be unsubscribed.


Event Filters

Filters let you narrow which events a webhook endpoint receives by matching against the event payload. Set filters via the filters attribute on a webhook endpoint. Filters are keyed by event type (e.g. people.changed).

How Matching Works

  • Plain value: exact match against the field
  • Array in filter: OR logic; matches if any element in the filter array matches the payload value
  • Array in both filter and payload: intersection; matches if there is any overlap between the two arrays
  • Nested object: AND logic; all keys in the object must match
  • Multiple keys at the same level: AND logic; every key must match

Supported Operators

OperatorDescription
$eqEqual to
$neqNot equal to
$inInclusion — array membership, or substring match for strings
$ninNot in — inverse of $in
$gt, $gteGreater than / greater than or equal
$lt, $lteLess than / less than or equal
$startsWithString starts with (accepts a single string or array of strings)
$endsWithString ends with (accepts a single string or array of strings)
$existsKey presence — true means key must be present, false means absent. A key with a null value is considered present.
$notNegation — inverts the nested condition
$orLogical OR — matches if any nested condition matches
$andLogical AND — matches if all nested conditions match

Examples

Filter for only created events

This filter receives people.changed events only when the action is created:

{
  "people.changed": {
    "meta": {
      "action": ["created"]
    }
  }
}

Filter for specific attribute changes

This filter receives people.changed events only when given_name or family_name changed:

{
  "people.changed": {
    "meta": {
      "changes": {
        "attributes": ["given_name", "family_name"]
      }
    }
  }
}

The meta.changes.attributes field lists which API fields changed on the resource. Array matching uses intersection — this filter matches if ANY of the listed attributes appear in the event's changed attributes.

Filter for specific additional info (data field) changes

This filter receives people.changed events only when the additional info schema demographics changed:

{
  "people.changed": {
    "meta": {
      "changes": {
        "data_field_schema_slugs": ["demographics"]
      }
    }
  }
}

Best Practices

1. Use Descriptive Names

Help identify endpoints in logs and dashboards:

// ✅ Good
name: "Production People Sync"
name: "Development Test Endpoint"

// ❌ Avoid
name: "Webhook 1"
name: "test"

2. Secure Your Signature Key

Store the signature_key securely:

// ✅ Good: Environment variable
const signatureKey = process.env.WICKET_WEBHOOK_SIGNATURE_KEY;

// ❌ Avoid: Hardcoded
const signatureKey = 'sk_live_abc123...';

3. Use HTTPS

Always use HTTPS URLs for production endpoints:

// ✅ Good
target_url: "https://your-domain.com/webhooks/wicket"

// ❌ Avoid (HTTP is insecure)
target_url: "http://your-domain.com/webhooks/wicket"

4. Separate Environments

Use different endpoints for development, staging, and production:

const endpoints = {
  development: 'https://dev.your-domain.com/webhooks/wicket',
  staging: 'https://staging.your-domain.com/webhooks/wicket',
  production: 'https://api.your-domain.com/webhooks/wicket'
};

5. Subscribe Only to Needed Events

Don't subscribe to events you won't use:

// ✅ Good: Only needed events
events: ['people.changed', 'organizations.changed']

// ❌ Avoid: All events when you only need a few
events: [
  'people.changed',
  'people.email_changed',
  // ... 10 more events you don't use
]

6. Monitor Endpoint Health

Regularly check your endpoints:

async function checkEndpointHealth() {
  const response = await fetch(
    `${apiUrl}/webhook/endpoints`,
    { headers }
  );

  const data = await response.json();

  data.data.forEach(endpoint => {
    console.log(`${endpoint.attributes.name}: ${endpoint.attributes.status}`);
  });
}

Troubleshooting

Endpoint Creation Fails

Problem: POST returns 422 Validation Error

Common causes:

  • Invalid target_url format
  • URL not publicly accessible
  • Invalid event type name
  • Missing required fields

Test Payload Not Received

Problem: Endpoint created but test payload never arrives

Solutions:

  • Verify target_url is publicly accessible
  • Check firewall rules allow incoming POST requests
  • Ensure your endpoint responds quickly (< 30 seconds)
  • Review server logs for incoming requests

Can't Update Endpoint

Problem: PATCH returns 404 Not Found

Solution: Verify you're using the correct endpoint UUID

On this page