CloudEvents v1.0

Why CloudEvents?

Every webhook provider uses a different payload format. CloudEvents standardizes the envelope structure so consumers can build generic event processors.

Quick Start

Enable CloudEvents in 2 steps:

curl -X POST https://hooksniff-api-1046140057667.europe-west1.run.app/v1/endpoints \n  -H "Authorization: Bearer hr_live_YOUR_KEY" \n  -H "Content-Type: application/json" \n  -d {"url": "https://your-app.com/webhooks", "format": "cloudevents"}

Standard vs CloudEvents Format

{
  "event": "order.created",
  "data": {
    "order_id": "ord_123",
    "total": 49.99
  }
}

{
  "specversion": "1.0",
  "type": "com.example.order.created",
  "source": "/hooksniff/endpoints/ep_abc123",
  "id": "evt_xyz789",
  "time": "2024-01-15T10:30:00Z",
  "datacontenttype": "application/json",
  "data": {
    "order_id": "ord_123",
    "total": 49.99
  }
}

Field Reference

• • specversion — specversion — CloudEvents spec version (always "1.0")
• • type — type — Event type in reverse domain notation
• • source — source — Event source (HookSniff endpoint path)
• • id — id — Unique event ID
• • time — time — Event timestamp (ISO 8601)
• • datacontenttype — datacontenttype — Payload content type
• • data — data — Original event payload

Migration Guide

Switching from standard format to CloudEvents:

1. Update your webhook receiver to handle the CloudEvents envelope
2. Extract the data field for the actual payload
3. Use the type field for event routing instead of the event query parameter
4. Test with the Playground before enabling for all endpoints

Benefits

• ✅ Standard format — Compatible with CloudEvents-aware tools and libraries
• ✅ Rich metadata — Includes spec version, source, content type
• ✅ Interoperability — Works with Knative, Argo Events, AWS EventBridge
• ✅ Future-proof — CNCF standard, widely adopted

Best Practices

• • Use reverse domain notation for type — com.yourcompany.resource.action
• • Always verify the specversion field — ensure it matches "1.0"
• • Use the id field for idempotency — deduplicate based on event ID
• • Parse the time field for ordering — events may arrive out of order

FAQ