When an event you have subscribed to occurs in Steppd, Steppd sends an HTTP POST request to your webhook URL with a JSON body describing the event. This page documents every available event type, the request headers, a sample payload, and how delivery retries work.
Available events
| Event | Triggered when |
|---|
document.created | A new document is created |
document.published | A document is published |
document.archived | A document is archived |
document.assigned | A document’s owner or editor is reassigned |
member.invited | A team invitation is sent |
member.joined | An invitee accepts and joins |
member.role_changed | A member’s role is changed |
| Header | Value |
|---|
Content-Type | application/json |
X-Steppd-Signature | HMAC-SHA256 signature of the request body, computed using your webhook secret |
X-Steppd-Signature to verify that a request originated from Steppd. See Verifying webhook signatures for implementation examples.
Example payload
The following shows the shape of a document.published event:
{
"event": "document.published",
"timestamp": "2024-01-15T10:30:00Z",
"organization_id": "org_abc123",
"data": {
"document_id": "doc_xyz789",
"title": "Employee Onboarding Process",
"version": "1.0",
"department": "HR",
"published_by": "user_def456"
}
}
| Field | Description |
|---|
event | The event type string (e.g., document.published) |
timestamp | ISO 8601 UTC timestamp of when the event was triggered |
organization_id | ID of the organization in which the event occurred |
data | Event-specific object containing relevant identifiers and metadata |
Delivery and retries
Steppd expects your endpoint to respond with a 2xx status code within a reasonable timeout. If the response is not 2xx or the request times out, the delivery is marked as failed and retried automatically.
Admins can view the full delivery history for all webhooks in the organization — including event type, status, number of attempts, and date — from Settings → Webhooks tab under Recent events.
Handling deliveries reliably
- Respond quickly. Return a
200 OK as soon as you receive the request and process the payload asynchronously if your handler logic takes time.
- Make your handler idempotent. The same event may be delivered more than once during retry cycles. Use the
timestamp and the IDs in the data object to detect and safely ignore duplicates.
- Verify the signature. Always check
X-Steppd-Signature before processing a payload to ensure the request is authentic.
Webhook event log (Admin)
Admins can inspect recent webhook activity from Settings → Webhooks → Recent events. The table shows the last 10 events across the entire organization.
| Column | Description |
|---|
| Event type | The event name (e.g., document.published) |
| Status | delivered, failed, or pending |
| Attempts | Number of delivery attempts made so far |
| Date | When the event was triggered |
