Webhook details for your developer

This article is for the developer connecting your system to Empath webhooks. It covers the message format, security and delivery rules.

What does a message look like?

Each message is an HTTP POST with a JSON body (unless you chose the Slack format):

{ "id": "…", // unique per event; the same on every retry "type": "course.assigned", "createdAt": "…", "tenantId": "…", // your Empath company id "data": { "user": { "id": "…" }, // plus email and displayName if personal data is on "object": { "type": "course", "id": "…", "title": "…" }, "actor": { … } } }

Event types: course.assigned, course.completed, knowledge_check.failed, content.published.

How do I check a message really came from Empath?

Every message carries two headers:

X-Empath-Timestamp: the send time, in Unix seconds.
X-Empath-Signature: sha256= followed by an HMAC-SHA256 of {timestamp}.{raw body}, using your webhook's signing secret.

Recompute the signature from the raw request body and compare. It's also good practice to reject messages whose timestamp is too old.

How does delivery work?

Your system must answer with a 2xx status within 10 seconds. Redirects count as failures.
Failed messages are retried up to 4 attempts in total: after about 1 minute, 5 minutes and 30 minutes. Each retry is signed again.
Messages can arrive out of order, and occasionally more than once. Use the id field (also sent as X-Empath-Delivery) to ignore duplicates.

Good to know

Empath may send each event type at most once per day, month or hour for the same person and item, to avoid floods.
Custom headers are sent as you configured them, except headers Empath uses itself.

Still need help?

Reach out to your Partner Success Manager, or email us at support@empathmsp.com. We’re happy to help!

Create a webhook
Check a webhook's health