Best practices

Operational guidance for reliable S2S and webhook integrations.

---

Security

• Rotate secrets if you suspect compromise; use regenerate-secret for webhook signing keys and re-issue API credentials per product policy.

• Never log raw API keys, secrets, or webhook signing secrets.

• Verify X-Kollect-Signature on every webhook before side effects.

---

Request signing

• Sync servers with NTP; signature timestamps are rejected outside ±300 seconds.

• Hash the exact raw HTTP body you send; avoid “pretty-print then sign” mismatches.

---

Idempotency

• Use a stable idempotency key per business transaction (order id, cart id, or UUID stored with the order).

• Do not reuse keys across different customers or amounts.

---

Webhooks

• Respond in under a few seconds (Kollect uses a 10s outbound timeout).

• Return 2xx after validation and enqueue fulfillment work.

• Implement idempotent handlers keyed by paymentId.

---

Failure handling

• 429: Retry with exponential backoff and respect details when present.

• 409: Resolve idempotency conflicts; do not blindly retry with the same key and altered body.

• 5xx: Retry create-payment only with the same idempotency key and unchanged body.

---

Redis and infrastructure

• If idempotency or rate limiting returns 503, involve platform ops; Redis may be required in production.

---

Related pages

• Rate limits

• Error handling