Production Readiness

Webhook Signature Verification & Idempotency

Verify 6MM Agent webhooks with the raw request body and process retries, timeouts, and repeated events without duplicate business actions.
View as Markdown

Webhooks notify a partner backend about asynchronous business-state changes. Because delivery may be retried, every receiver must verify the signature before parsing trusted data and must process the event idempotently.

Webhook headers

HeaderDescription
X-Agent-TimestampUnix timestamp in seconds.
X-Agent-NonceReplay-protection nonce.
X-Agent-SignatureHMAC-SHA256 signature.
timestamp + nonce + rawBody

Use the exact raw request body received over HTTP when reconstructing the signed value. Parsing and re-serializing JSON first can change whitespace or field order and produce a different signature.

Verification flow

  1. Read the timestamp, nonce, and signature headers.
  2. Capture the unmodified raw request body.
  3. Build timestamp + nonce + rawBody.
  4. Calculate HMAC-SHA256 with the partner API secret.
  5. Compare the calculated and received signatures using a constant-time comparison.
  6. Apply the approved timestamp-freshness and nonce-reuse checks.
  7. Parse and process the event only after verification succeeds.

When an official Agent SDK verifier is available, use it instead of maintaining independent signing code.

Order idempotency

CaseHandling
Initial transfer requestCreate one globally unique agentOrderNo.
HTTP timeoutQuery the original agentOrderNo before creating a new one.
PROCESSING responseWait for webhook or query order status.
Repeated webhookDeduplicate by idempotency key and final status.

Store enough information to recognize a repeated delivery and recover safely:

FieldPurpose
Event or business keyUniquely identifies the notification or operation.
Partner order numberConnects the event to the original request.
Payload hashHelps identify conflicting repeated payloads.
Current processing stateDistinguishes received, processing, succeeded, and failed work.
Final business statusPrevents a terminal action from being applied twice.
Processed timestampSupports investigation and retention policies.

Commit the business change and idempotency record in the same transaction where possible. A repeated event should return the already-known result instead of applying the balance, order, or user change again.

Timeout and retry rule

An HTTP timeout does not prove that the original request failed. Query the operation using the original agentOrderNo, or wait for its webhook, before deciding whether another action is required. Creating a new business order number after every timeout can cause duplicate fund movements.

Production checklist

  • Verify the signature before JSON parsing or business processing.
  • Preserve the raw body independently from the parsed payload.
  • Reject stale or replayed requests according to the approved integration policy.
  • Make event processing safe for repeated and out-of-order delivery.
  • Log event IDs, partner order numbers, processing result, and request time.
  • Redact secrets and signature values from logs and support attachments.
Secrets & HMAC Signing

Protect the API secret used for request and webhook verification.

Agent SDK Overview

Review the complete backend integration workflow.

SDK Troubleshooting

Investigate rejected signatures, repeated events, and pending operations.