Webhooks

Webhooks are a way to receive real-time updates from Clasp. They allow your application to be notified automatically when certain events occur in Clasp, eliminating the need to continuously poll the API for changes.

Overview

When an important change happens in your Clasp account (like a member being updated or an employer being created), Clasp generates an event and sends an HTTP POST request to your configured endpoint with details about what changed. Please reach out to Clasp to get started.

Event Payload

Each event is sent as a JSON payload with the following structure:

{
  "id": "evnt_8Ln4MbSf5uLFurmAOfNr9",
  "event_type": "updated",
  "object_id": "er_67Al5UIOFMPsrHbLI8YnU", 
  "object_type": "employer",
  "employer": "er_67Al5UIOFMPsrHbLI8YnU",
  "created_at": "2025-01-06T05:41:19.093833Z"
}

Field Descriptions

• id: Unique identifier for the event
• event_type: The type of change that occurred
• object_id: Identifier of the object that changed
• object_type: Type of object that changed
• employer: Identifier of the employer the object belongs to
• created_at: Timestamp when the event occurred

Supported Events

Object Types	Event Types
- member	- created
- dependent	- updated
- employer	- deleted
- payroll_benefit
- open_enrollment_window
- enrollment
- business_unit

Security

Verifying Webhook Signatures

Every webhook request includes two important headers:

1. Clasp-Event-Timestamp: When the event was sent
2. Clasp-Event-Signature: HMAC signature of the event

To verify the event is legitimate via the signature:

1. Concatenate the event payload with the timestamp: ${payload}.${timestamp}
2. Create an HMAC SHA-256 digest with the shared secret
3. Compare the calculated signature with Clasp-Event-Signature

Here’s a Python example of signature verification:

import hashlib
import hmac
import json

def verify_event(payload, timestamp, signature, secret):
    # Calculate expected signature
    message = f"{json.dumps(payload)}.{timestamp}".encode("utf-8")
    expected = hmac.new(
        secret.encode('utf-8'),
        message,
        hashlib.sha256
    ).hexdigest()
    
    # Compare the digests
    return hmac.compare_digest(expected, signature)

Best Practices

1. Response

• Return a 200 status code as quickly as possible
• Store the event ID to prevent duplicate processing
• New event and object types will be added over time. Ensure a 200 response is returned for all events
• Clasp will retry failed event deliveries up to 10 times when an error response is returned

2. Fetching Current Data

• Use the object_type and object_id to determine which API endpoint to query
• Fetch the current state from the API