Zintara webhook event schema and signature reference

Define the decision

The reviewed implementation supports reply.received and bounce.detected subscriptions. A manual connection test emits test.event. All use a JSON object containing event, data and an RFC3339 UTC timestamp. The legacy X-Coldreach header names remain part of the wire format.

Work through the procedure

1. Read the exact raw body before JSON parsing.
2. Calculate HMAC-SHA256 with the endpoint signing secret.
3. Compare the expected sha256= hexadecimal value with X-Coldreach-Signature using a timing-safe comparison.
4. Parse and validate the event schema only after verification.
5. Handle unknown fields defensively and reject unsupported actions.

Worked example

The following is a synthetic example for this procedure, not a customer result or performance benchmark.

Headers: Content-Type: application/json
X-Coldreach-Event: reply.received
X-Coldreach-Signature: sha256=<hex HMAC of exact body bytes>
reply.received data: email, subject, leadId
bounce.detected data: email, leadId
test.event data: message
Envelope fields: event, data, timestamp

Read the result

Reserializing parsed JSON before verification can change bytes and invalidate the comparison. The signature authenticates the body; timestamp freshness requires a receiver policy, and neither the timestamp nor signature is a stable event identifier.

Check before moving on

1. Test a valid payload, an altered byte and an invalid signature.
2. Keep business processing repeat-safe and persist before acknowledging.

Limits and next action

There is no documented durable replay, stable event ID or complete message-body export in this contract. Review the deployed version before relying on an expanded schema.

Source: Zintara product context