Delivery Envelope

JSON shape, headers, and receiver checklist for every Skillhabit webhook delivery.

What This Is For

Every Skillhabit webhook delivery uses the same JSON envelope. Your receiver should parse the envelope first, then branch on eventType before reading data.

Who This Is For

Developers implementing or hardening the HTTPS endpoint configured under Configure → Connections → Webhooks.

Envelope Fields

Field	Description
`id`	Unique id for this webhook delivery—use as an idempotency key
`createdAt`	Delivery creation timestamp in epoch milliseconds (UTC)
`workspace`	Customer / workspace id
`eventType`	Logical event name (also sent in the `Event-Type` HTTP header)
`data`	Event-specific JSON object

Headers

Event-Type — same value as eventType in the body
Any custom headers you configured on the webhook in Configure (for example a shared secret your side checks)

Content type is JSON. Treat unknown fields in data conservatively: ignore what you do not need, and fail closed only when a field you require is missing.

Receiver Checklist

Respond quickly with 2xx so Skillhabit can treat the delivery as accepted
Deduplicate on id if you may receive retries
Branch on eventType before parsing data
Keep endpoint URLs on HTTPS and rotate any shared secrets you put in custom headers
Log workspace, eventType, and id together so support can correlate a delivery

Example Shape

{
  "id": "delivery-uuid",
  "createdAt": 1717200000000,
  "workspace": "acme",
  "eventType": "progress.course.evaluated",
  "data": {}
}

data contents vary by event. Use the Event Catalog for names and when they fire; use your integration tests or logged deliveries for the exact data fields you depend on.