clio-webhooks

Clio Webhooks

When to Use This Skill

• How do I receive Clio webhooks?
• How do I verify Clio webhook signatures (X-Hook-Signature)?
• How do I complete the Clio X-Hook-Secret handshake / activation?
• How do I handle created, updated, deleted, or matter lifecycle events?
• Why is my Clio webhook signature verification failing?
• How do I keep a Clio webhook from expiring?

How Clio Webhooks Work

Clio Manage delivers webhooks in two distinct kinds of POST request to your URL:

1. Handshake — Immediately after a webhook is created (or its URL changes), Clio sends a POST containing an X-Hook-Secret header with a freshly generated shared secret. Your endpoint must confirm it (echo the same header back with 200 OK). Clio's docs say the webhook is not enabled until the handshake succeeds — though in one observed EU test the webhook auto-enabled and began delivering without any handshake request arriving (see references/setup.md). Implement the echo regardless: it is how you obtain the secret, and it is the key for verifying every later event.
2. Events — Every subsequent delivery is signed. Clio computes HMAC-SHA256(shared_secret, raw_request_body) and puts the digest in the X-Hook-Signature header. Verify it against the raw body.

Clio does not ask you to supply the secret when creating the webhook — Clio generates it and hands it to you during the handshake. Save it (e.g. keyed by webhook_id) as CLIO_WEBHOOK_SECRET.

Verification (core)

X-Hook-Signature is the HMAC-SHA256 digest of the raw body, keyed with the shared secret. Pass the raw body (never re-serialized JSON) and compare timing-safe.

Clio's docs state only that it "will compute an HMAC-SHA256 signature based on the shared secret and the request body" — they never say whether the digest is hex or base64 encoded.

Verified against a live delivery: it is lowercase hex (64 characters). This was confirmed by recomputing HMAC-SHA256 over the raw body with the webhook's shared_secret and matching the header exactly. The handlers below still compute the digest once and accept either encoding, so they keep working if Clio ever differs by region or changes it — but hex is what you should expect.