Skip to main content

Events

An event is a notification sent from your applications to Hook0 when something happens. Events carry data from producers to consumers through the webhook system.

Key points​

  • Events belong to an Application
  • Each event has an Event Type that categorizes it
  • Events carry a payload in JSON, plain text, or base64 format
  • Labels on events control routing to matching Subscriptions
  • Events are immutable once created

Event lifecycle​

Payload formats​

Hook0 supports three payload content types:

  • application/json: structured data for API integrations
  • text/plain: simple string data
  • application/octet-stream: binary data encoded as base64

The payload is delivered exactly as received, with no transformation.

Payload as String

When sending JSON payloads via the API, the payload must be a JSON-encoded string, not a raw object. This ensures Hook0 forwards it exactly as provided.

Routing with labels​

Every event must include at least one label. Labels are key-value pairs that Hook0 uses to match events with subscriptions:

  1. Event is created with labels (e.g., tenant_id: "acme")
  2. Hook0 finds subscriptions with matching label filters
  3. Request attempts are created for each match

Idempotency​

Each event has a unique event_id (UUID). The event_id field is optional when ingesting events — if omitted, the server generates a UUIDv7 automatically. If you provide your own event_id and send the same ID twice, Hook0 rejects the duplicate. This prevents accidental double-delivery when clients retry with the same event_id.

What's next?​