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:
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Descriptive name for the endpoint |
target_url | string | Yes | HTTPS URL to receive webhook POSTs |
status | string | Yes | active or inactive |
events | array | Yes | List of event types to subscribe to |
filters | object | No | JSON 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:
- Respond with a 2xx status code
- 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
endListing Webhook Endpoints
Request
GET /webhook/endpoints?page[number]=1&page[size]=25Response
{
"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
| Operator | Description |
|---|---|
| $eq | Equal to |
| $neq | Not equal to |
| $in | Inclusion — array membership, or substring match for strings |
| $nin | Not in — inverse of $in |
| $gt, $gte | Greater than / greater than or equal |
| $lt, $lte | Less than / less than or equal |
| $startsWith | String starts with (accepts a single string or array of strings) |
| $endsWith | String ends with (accepts a single string or array of strings) |
| $exists | Key presence — true means key must be present, false means absent. A key with a null value is considered present. |
| $not | Negation — inverts the nested condition |
| $or | Logical OR — matches if any nested condition matches |
| $and | Logical 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_urlformat - 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