Defining Events and Payloads
Document webhook event types with trigger conditions, categories, HTTP headers, payload schemas, and concrete JSON examples. Covers thin versus fat event strategies, event naming conventions, header standards, and schema integration for end-to-end data lineage.
Webhook event definitions are the core of any webhook API. Each event type describes what happened, when it happened, and what data is included in the delivery. Well-documented events enable consumers to build targeted integrations that subscribe only to the events they need, verify payload structures against documented schemas, and process events correctly using the provided headers and metadata.
Event Structure
Each webhook event definition in NeoArc captures the following elements.
Event Naming Conventions
Consistent event naming is essential for discoverability, subscription filtering, and consumer routing logic.
| Pattern | Examples | When to Use |
|---|---|---|
| resource.created | order.created, user.created | A new entity was created in the system |
| resource.updated | order.updated, profile.updated | An existing entity was modified |
| resource.deleted | subscription.deleted, webhook.deleted | An entity was removed from the system |
| resource.action | payment.processed, order.fulfilled, invoice.finalised | A domain-specific action was performed on the entity |
| resource.sub-resource.action | order.item.added, user.address.updated | A nested resource within a parent entity changed |
Event Categories
Categories group related events for navigation and subscription management. Each event type belongs to exactly one category.
Trigger Conditions
Trigger conditions describe the precise business event that causes the webhook to fire. This is one of the most valuable fields in webhook documentation because it answers the question that every consumer asks: "When exactly will I receive this event?"
HTTP Headers
Webhook deliveries include HTTP headers that provide metadata about the event. Document all headers so consumers can implement verification, deduplication, and routing logic.
| Header | Purpose | Example Value |
|---|---|---|
| X-Event-ID | Unique identifier for deduplication | evt_1a2b3c4d5e6f7a8b |
| X-Event-Type | Event name for routing | order.created |
| X-Timestamp | ISO 8601 delivery timestamp | 2026-02-25T14:30:00.000Z |
| X-Webhook-Signature | HMAC signature for verification | sha256=a1b2c3d4e5f6... |
| Content-Type | Payload content type | application/json |
| X-Delivery-Attempt | Current delivery attempt number | 1 |
| X-Webhook-ID | Subscription identifier | whk_9z8y7x6w5v4u |
Thin versus Fat Events
The payload strategy determines how much data is included in each webhook delivery. This is a fundamental design decision that affects consumer architecture, network bandwidth, and API coupling.
Payload Schema Integration
Webhook event payloads reference schemas from your workspace's shared schema library. This provides type safety, reusability, and end-to-end data lineage.
Concrete Examples
Every event definition should include at least one concrete JSON example showing both headers and payload. Examples serve as the single most useful reference for consuming developers.
Example: E-Commerce Webhook Events
The following event definitions demonstrate the documentation format for a complete e-commerce webhook API.
Order Events
Order lifecycle events fire as orders progress from creation through fulfilment.