Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.steppd.com/llms.txt

Use this file to discover all available pages before exploring further.

Webhooks let Steppd push a structured JSON payload to your endpoint the moment something happens in your organization. You configure each webhook with a URL and a list of event types to subscribe to. Steppd delivers a POST request for every matching event. There are six event types in total, grouped into two categories.
Webhooks are available on the Scale plan only. See Profile → Webhooks to create and manage your webhook endpoints.

​
Event types

​
Document events

These four events cover the document lifecycle. See Document events for field-level detail on each.
EventWhen it fires
document.createdA new document is created
document.publishedA draft is published and becomes the live version
document.revisedA revision draft is published
document.archivedA published document is archived

​
Member events

These two events cover team membership changes. See Member events for field-level detail on each.
EventWhen it fires
member.invitedAn admin invites a new team member by email
member.role_changedA member’s role is changed between admin and member

​
Common payload envelope

Every webhook delivery wraps its event-specific data in a common envelope: 
{
  "event": "document.published",
  "timestamp": "2024-01-15T10:30:00Z",
  "organization_id": "org_abc123",
  "data": {
    "document_id": "doc_xyz789",
    "title": "Employee Onboarding Process",
    "version": "2.0",
    "department": "HR",
    "published_at": "2024-01-15T10:30:00Z",
    "published_by_email": "alice@example.com",
    "sections": []
  }
}
​
event
string
required
The event type string, for example document.published. Use this field to route the payload in your handler.
​
timestamp
string
required
ISO 8601 UTC timestamp of when the event was fired.
​
organization_id
string
required
The ID of the Steppd organization in which the event occurred.
​
data
object
required
The event-specific payload. Shape varies by event type, see the detail pages for each category.

​
Responding to deliveries

Your endpoint must return a 2xx HTTP status within a reasonable timeout to acknowledge delivery. Steppd records the HTTP status of each delivery attempt. If your endpoint returns a non-2xx status or times out, the delivery is marked as failed. You can review delivery history in Profile → Webhooks.
You can send a test payload to any configured webhook from Profile → Webhooks without triggering a real event or affecting your publish count. This is useful for verifying your endpoint handles the envelope correctly before going live.

​
Webhook security

When you create a webhook, Steppd generates a signing secret that is shown once. You can use this secret to verify that incoming requests originate from Steppd by checking the HMAC signature on the payload.

​
Detail pages

Document events

Field-level reference for all four document lifecycle events.

Member events

Field-level reference for both team membership events.