Webhook Event Types — Proposed Guide

Webhook Event Types: Event types should express durable business facts with clear names and versioned payloads. A name such as expense.approved describes…

Overview

Event types should express durable business facts with clear names and versioned payloads. A name such as expense.approved describes a decision, not a reimbursement.

Key concepts

Define the producer, resource type, occurrence time and minimal context for each event. Keep schema version explicit.

Implementation considerations

All event names are proposed. Do not build a production subscriber that assumes this catalog or its payloads are final.

Illustrative data model

This local fixture shows a possible representation for the concepts above. It is not an endpoint response, production configuration or a claim that the described capability is implemented.

{
  "reference_only": true,
  "topic": "Webhook Event Types",
  "event_type": "expense.updated",
  "schema_version": "preview-1",
  "resource_type": "expense",
  "resource_id": "resource_example_123"
}

Design review checklist

• Document which organization owns the webhook event types representation and which actor may view or change it.
• Test the boundaries of event type, schema version, resource type, resource id using synthetic values, including missing or inconsistent references.
• Before future implementation, obtain an approved contract and review failure behavior. This documentation does not authorize production activation.

Proposed data types

Related documentation