Webhook Dispatcher — Sync Contract
Status: populated
Owner: Platform Engineering
Last updated: 2026-04-18
Companion: API_CONTRACTS · EVENT_SCHEMAS
1. Upstream Dependencies
dlr-processor → webhook.dispatch
| Aspect | Detail |
|---|
| Owner | dlr-processor team |
| Schema version | 1.0 |
| Stability guarantee | Additive changes without notice; breaking changes = 30-day parallel publish |
| Required fields | eventId, accountId, messageId, dlrStatus, to, operatorId, occurredAt |
| Webhook Dispatcher commitment | Tolerant reader; ignores unknown fields; logs schema version mismatch |
auth-service / Kong — JWT validation
| Aspect | Detail |
|---|
| Owner | auth-service team |
| Contract | Kong injects X-Account-Id header after JWT validation |
| Breaking change | Header name change requires coordinated deployment |
KMS (secret encryption)
| Aspect | Detail |
|---|
| Owner | Cloud Platform team |
| Contract | GenerateDataKey + Decrypt API for envelope encryption |
| Availability | 99.99% SLA; brief unavailability handled by in-memory secret cache (5 min TTL) |
2. Downstream Dependencies
Customer webhook endpoints (external)
| Aspect | Detail |
|---|
| Contract | Customer commits to: HTTPS endpoint, 2xx on receipt, idempotency on X-Ghasi-Delivery-Id |
| Ghasi commitment | Same deliveryId used on all retries of same event; customer can use this for dedup |
| Signature verification | Documented in customer integration guide |
3. Schema Change Protocol
Same as platform-wide protocol:
- Additive change: deploy producer first, no consumer coordination required.
- Breaking change: new versioned subject (
webhook.dispatch.v2), parallel publish 30 days minimum.
- Emergency: 48-hour minimum notice; rollback plan required.
4. REST API Versioning
The REST API is versioned via path prefix (/v1/). Minor/patch changes (additive fields) are non-breaking. New major version (/v2/) required for breaking changes. Old version deprecated with 90-day sunset notice.