Professional API: Webhooks

Have your own systems told when something happens in your practice, instead of polling for it.

Last reviewed

How webhooks work here

A signed POST to an endpoint you register.

The shape of a delivery

You register an HTTPS endpoint on the Webhooks page (/account/developer/webhooks) and choose which events it should receive. When one of those events occurs, TheWILL.ai sends a JSON POST to your endpoint, signed with a secret unique to that endpoint.

Anything other than a 2xx response counts as a failure and is retried. A delivery attempt is abandoned if your endpoint has not responded within 10 seconds.

Note

Webhook access is an entitlement on your plan, separate from API access. If your endpoint never fires, check that your plan includes webhooks before debugging your own receiver.

The professional events

Every event a professional endpoint can subscribe to.

Event slugs

  • appointment.created: a new appointment has been booked with your practice
  • appointment.rescheduled: an existing appointment has moved
  • appointment.cancelled: an appointment has been cancelled
  • engagement_letter.signed: a client has signed an engagement letter
  • approach.received: someone has approached your practice through the platform
  • message.received: a client has sent a new message in a conversation with you
  • referral.will_started: someone who arrived through your white-label partner page has started a will
  • referral.will_completed: a will started through your partner page has been signed and completed
  • client.created: a new client has been added to your practice
  • client.withdrawn: a client has withdrawn from your practice
  • client.rejoined: a client who withdrew has come back to your practice
  • will.status_changed: a client’s will has moved to a new status
  • will.generation_completed: a will you created through the Professional API has finished generating
  • will.generation_failed: a will you created through the Professional API failed to generate or was cancelled
  • will_review.requested: a client has asked for their will to be reviewed
  • invoice.issued: an invoice has been issued to a client
  • invoice.paid: an invoice has been paid
  • complaint.opened: a client has opened a complaint
  • task.due: a matter task that is not yet done falls due today
  • estate_plan.status_changed: the status of a client’s estate documents has changed, sent only while that client consents to your firm seeing it

Tip

Subscribe only to the events you act on. Clearing an endpoint’s event list is also how you pause it without deleting it. Deleting the endpoint destroys its signing secret, which cannot be shown to you again.

Payloads

Identifiers and status, and nothing else.

What is in the body

A professional webhook payload carries the event slug, the identifier of the object that changed, named for it (for example appointment_id, client_id or invoice_id), and, where the object has one, its status. A few events add the identifier of the parent record as well: message.received carries conversation_id, task.due carries matter_id and will_review.requested carries will_id.

estate_plan.status_changed carries the client_id and a documents list: for each estate document, its type, whether it is not started, in progress or done, when the client last reviewed it and any factual reason to review it. It never carries what a document says, and it is sent only for a change, never for a save that changed nothing.

The two will generation events carry the id your create request was answered with, your own client_reference, a status of completed or failed and an occurred_at time. will.generation_failed adds a reason: cancelled when the generation was cancelled, otherwise error.

Client names, contact details, matter content and message bodies are never in the payload. That is deliberate: a webhook travels to an endpoint we do not control, so it carries only enough to tell you which record changed. Your receiver then fetches whatever detail it needs over the Professional API, authenticated as you and subject to the same consent rules.

Note

This means a webhook alone is never enough to act on. Treat it as a signal to fetch, not as the data itself.

Headers on every delivery

  • X-Webhook-Signature: the body-only HMAC signature described below. Deprecated, because a captured delivery can be replayed and still verify: check webhook-signature instead
  • X-Webhook-Event: the event slug, so you can route without parsing the body
  • X-Webhook-ID: a fresh identifier per delivery attempt, so it differs on every retry
  • X-Webhook-Timestamp: the delivery time in Unix seconds
  • webhook-id: a msg_-prefixed identifier for the event itself, which stays the same on every retry of it (Standard Webhooks)
  • webhook-timestamp: the same Unix-seconds delivery time (Standard Webhooks)
  • webhook-signature: a v1,-prefixed base64 HMAC-SHA256 that also covers the identifier and timestamp (Standard Webhooks). During a signing-secret rotation overlap it holds two space-separated signatures, one per secret
  • Content-Type: application/json

Verifying the signature

Prove the delivery came from us before you act on it.

How to verify

  1. Take the raw request body bytes, exactly as received. Do not parse and re-serialise the JSON first, because any reordering or whitespace change breaks the signature
  2. Join the webhook-id header, a full stop, the webhook-timestamp header, a full stop and those bytes, then compute an HMAC-SHA256 of the result using your endpoint’s signing secret as the key and base64-encode it
  3. Compare v1, followed by your result with each space-separated value in the webhook-signature header, using a constant-time comparison, not ==
  4. Reject the delivery if none matches or the timestamp is more than a few minutes old, and only then parse the body

Important

X-Webhook-Signature signs the body only. It is a deprecated hex HMAC-SHA256 with no timestamp in its signed string, so it cannot prove freshness: a captured delivery can be replayed and still verify. Move any handler that checks it to webhook-signature. To ignore repeats, record the webhook-id values you have already processed. Do not key on X-Webhook-ID: it is new on every attempt, so a retry would never match it.

Rotating the signing secret

When you rotate an endpoint’s signing secret, the current secret keeps working for 24 hours by default, so you can update your receiver without failed deliveries. During that overlap every delivery’s webhook-signature carries a signature made with each secret, and a receiver holding either one verifies: accept the delivery if any space-separated v1, value matches. If the secret may have leaked, choose to end it now instead. The deprecated X-Webhook-Signature header is signed with the new secret only.

The code below checks webhook-signature and turns away deliveries more than five minutes old. Run it on the raw request body, before any JSON parsing. More worked examples are in the integration recipes.

import base64
import hashlib
import hmac
import time

def verify_webhook(raw_body, secret, headers, tolerance_seconds=300):
    """True when a delivery is signed with your endpoint secret and is recent."""
    timestamp = headers["webhook-timestamp"]
    if abs(time.time() - int(timestamp)) > tolerance_seconds:
        return False  # too old: a captured delivery being replayed
    signed = f"{headers['webhook-id']}.{timestamp}.".encode() + raw_body
    expected = base64.b64encode(
        hmac.new(secret.encode("utf-8"), signed, hashlib.sha256).digest()
    ).decode()
    return any(
        hmac.compare_digest(f"v1,{expected}", candidate)
        for candidate in headers["webhook-signature"].split(" ")
    )


# Flask: verify the raw bytes before you parse them
@app.post("/webhooks")
def receive_webhook():
    if not verify_webhook(request.get_data(), os.environ["WEBHOOK_SECRET"], request.headers):
        abort(401)
    handle_event(request.get_json())
    return "", 204
import crypto from "node:crypto";

export function verifyWebhook(rawBody, secret, headers, toleranceSeconds = 300) {
  const timestamp = headers["webhook-timestamp"];
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > toleranceSeconds) return false;
  const expected = crypto
    .createHmac("sha256", Buffer.from(secret, "utf8"))
    .update(`${headers["webhook-id"]}.${timestamp}.`)
    .update(rawBody)
    .digest("base64");
  const wanted = Buffer.from(`v1,${expected}`);
  return headers["webhook-signature"].split(" ").some((candidate) => {
    const given = Buffer.from(candidate);
    return given.length === wanted.length && crypto.timingSafeEqual(given, wanted);
  });
}

// Express: take the raw body, verify, then parse
app.post("/webhooks", express.raw({ type: "application/json" }), (req, res) => {
  if (!verifyWebhook(req.body, process.env.WEBHOOK_SECRET, req.headers)) return res.sendStatus(401);
  handleEvent(JSON.parse(req.body));
  return res.sendStatus(204);
});

Retries and failures

What happens when your endpoint is down.

The backoff schedule

A failed delivery is retried on a widening schedule: immediately, then after 1 minute, 5 minutes, 30 minutes, 2 hours, and then once daily for up to 5 days.

After 10 consecutive failures the endpoint is deactivated and the account owner is emailed. The Developer hub then shows it as Inactive; once your receiver is healthy again, choose Reactivate on that endpoint to start delivering again with a fresh failure count. An endpoint registered through an API key that has since been revoked or has expired cannot be reactivated; register it again instead.

To have one logged delivery sent again yourself, call POST /api/v1/portfolio/webhooks/{id}/deliveries/{delivery_id}/redeliver/. It re-sends that event’s original body with a fresh signature and timestamp, and is recorded as a new delivery. Each event can be redelivered up to ten times, and only while the endpoint is active.

Delivery history, including each payload sent, is kept for 90 days and then deleted automatically. A delivery older than that can no longer be redelivered; the request returns 404 with the code WEBHOOK_DELIVERY_UNAVAILABLE.

Note

Retries replay the original body byte for byte, so the signature stays valid across attempts. It also means your receiver must be idempotent: the same event can legitimately arrive more than once.

Building a reliable receiver

  • Verify the signature, then acknowledge with a 2xx quickly and do the real work afterwards, because slow handlers time out and get retried
  • De-duplicate on webhook-id, which repeats on a retry, never on X-Webhook-ID, which does not
  • Fetch the detail you need from the Professional API rather than waiting for a richer payload
  • Monitor your endpoint, because 10 consecutive failures will switch it off

Can’t find what you’re looking for?

Our support team is here to help. Contact us and we’ll get back to you as soon as possible.

Contact us

We use cookies to improve your experience. See our Cookie policy (opens in a new tab) for details.