Developer guide · Webhook security
Verify webhook signatures before trusting the payload.
A valid signature proves possession of the shared endpoint secret for that exact body. It does not remove duplicate, replay, authorization, privacy, or monitoring duties.
- Signed input
- Exact raw request body
- Algorithm
- HMAC-SHA256
- Duplicate key
- Delivery ID
Short answer
Authenticate the exact bytes received.
Reward Loyalty signs each outbound webhook from the exact raw request body with HMAC-SHA256 and the endpoint secret, then sends the Base64 result in the documented signature header. The receiver must compare the expected value in constant-time before parsing JSON. That check authenticates the body for a holder of the secret; it does not prevent replay, suppress duplicates, or authorize a write back into Reward Loyalty.
Decision criteria
Treat the signature as one security control.
Authenticity, duplicate defense, replay handling, secret storage, privacy, and command authorization solve different risks.
Verification point
Capture the unmodified request bytes before middleware parses, reformats, or re-encodes the JSON body.
Secret lifecycle
Store the one-time endpoint secret outside source and logs, restrict access, and plan an immediate cutover when it rotates.
Trust after verification
Validate the event name and schema, enforce the receiver’s own authorization, and keep webhook input away from a generic command executor.
Signature boundary
Know what the HMAC proves.
This guide covers Reward Loyalty outbound webhooks. Shopify and WooCommerce inbound webhook signatures use their own documented contracts.
Input bytes
Compute the expected HMAC from the exact raw request body. Parsing and re-encoding JSON can change bytes while preserving meaning and will break verification.
Header value
Read the current Reward Loyalty signature header, remove the documented algorithm prefix, Base64-decode with strict validation, and reject malformed input.
Comparison
Compare binary values with a constant-time function. Reject a missing, malformed, or mismatched signature before any event processing.
Authorization
A valid signature proves knowledge of the shared secret for that body. It does not grant Agent API scope, member consent, or permission to perform a reverse write.
Receiver pipeline
Accept fast, process under your own controls.
The public endpoint should do little work before it returns.
-
1
Read and verify
Capture the raw body, verify the HMAC, enforce a size limit, then parse JSON and validate the envelope and supported event name.
-
2
Claim the delivery ID
Write the delivery ID to a durable uniqueness boundary before starting a side effect. Return success for a duplicate already accepted.
-
3
Persist minimal work
Store the small event record or queue message the downstream task needs, with trace identifiers and no avoidable personal data.
-
4
Respond and process
Return a successful response after durable acceptance. Run slow CRM, automation, reporting, or deletion work behind the receiver.
Duplicate and replay defense
Signatures do not make delivery exactly once.
The outbound contract is at-least-once, and a captured valid request has no new signature requirement when replayed unchanged.
Delivery ID
Use the delivery ID for side-effect deduplication. Keep the event ID and correlation ID for tracing, not as substitutes for the delivery key.
Replay policy
Retain processed delivery IDs for a period that matches the system’s risk and recovery policy. The receiver owns any extra time, network, or business-rule checks.
Ordering
Do not assume events arrive in business order. Read current state through a supported API or apply an event-specific reconciliation rule when order matters.
Failed work
Separate HTTP receipt from downstream completion. Keep retry count, next attempt, terminal status, and operator action in the receiver’s own job record.
Security operations
Prepare rotation and incident evidence.
Secret care and useful logs matter after the first valid request.
Secret storage
The endpoint secret is shown once and stored encrypted by Reward Loyalty. Store the receiver copy in its secret manager, never in source, URLs, payloads, or routine logs.
Secret rotation
Rotation replaces the active secret at once. Coordinate receiver deployment and endpoint rotation so the verification key changes without a hidden fallback.
Privacy and logs
Log delivery, event, correlation, result, and reason codes. Hash or omit member fields and raw bodies unless a defined incident policy requires protected retention.
Brand scope
White-label relevance: Irrelevant. Installation branding does not change HMAC verification, receiver authorization, duplicate control, or incident responsibility.
Product and operating limits
Do not promote a valid signature into broad trust.
- Reward Loyalty signs outbound webhook bodies. This page does not define the separate Shopify or WooCommerce signature formats used for incoming commerce events.
- Signature verification does not provide encryption, freshness, ordering, exactly-once delivery, or permission to call a write API.
- Secret rotation is an immediate security action. The operator and receiver developer own the coordinated cutover, monitoring, and incident response.
Implementation guides
Use current documentation for changing details.
Requirements, interfaces, settings, limits, and release behavior belong in the maintained product documentation.