Introduction
Webhooks are the backbone of automated integrations between Affilentra, payout providers, accounting tools and partner systems. However, without secure signatures and replay protection these connections become attack surfaces: manipulated events, duplicate payouts, or forged settlements can occur. This article demonstrates practical steps for merchants and network operators on the self-hosted Affilentra platform to sign incoming and outgoing webhooks, prevent replay attacks, and verify integrations robustly.
Fundamentals of Webhook Security
Securing webhooks relies on a few essential components:
- Confidential secrets (shared secrets) per integration
- Payload integrity verification via signature (e.g., HMAC)
- Replay protection using timestamps and nonces
- HTTPS/TLS for transport encryption
- Logging, monitoring, and key rotation
Affilentra supports these mechanisms with role-based responsibilities: platform operators manage system keys, merchants set integration secrets, and partners receive traceable tracking links and payout records.
Incoming Webhooks: Validation Steps for Merchants
When third parties (e.g., payout providers) send events to your Affilentra instance, you should perform the following checks before taking any actions:
1) Transport Check
- Accept HTTPS only. Redirect HTTP requests to HTTPS or reject them.
2) Signature Validation
Require an HMAC signature computed over the raw request body and a shared secret. Recommended header name: X-Affilentra-Signature. Procedure:
- Compute HMAC-SHA256(raw_body, secret) → hex/base64
- Compare with header value using a time-constant comparison function
Important: Sign the exactly received raw text (not the parsed JSON) to avoid canonicalization issues.
3) Timestamp and Replay Protection
Also require a timestamp header (e.g., X-Affilentra-Timestamp) and check:
- The timestamp falls within a short window (e.g., ±300 seconds) relative to system time.
- Optional: Verify an additional X-Affilentra-Nonce and store used nonces for the duration of the time window. Each nonce may be accepted only once.
With timestamp + nonce you prevent a captured request from being replayed later.
4) Event ID and Idempotency
Require a unique event ID in the payload (e.g. event_id). Ensure each event ID is processed only once; on repeated deliveries processing should be idempotent and return a 2xx status with an appropriate indication.
Outgoing Webhooks: Signing Affilentra Events
When your Affilentra installation sends events to payout providers, accounting systems or partners: sign outgoing requests consistently and document the format for integration partners.
Signing Header
- Include: X‑Affilentra‑Timestamp, X‑Affilentra‑Signature, optional X‑Affilentra‑Nonce
- Signing string: concatenation of timestamp + '.' + raw_body
Example flow: timestamp = current UNIX seconds; signature = HMAC‑SHA256(timestamp + '.' + raw_body, provider_secret)
Delivery and Acknowledgement
- Expect a 2xx response from the recipient. On 5xx or network errors: retries with exponential backoff.
- On 4xx: no automatic retries without manual review (e.g. 401 = incorrect signature/secret).
- Log the request, response code, duration and signature verification result for audits.
Preventing Replay Attacks: Practical Concepts
Replay protection combines simple mechanisms that together are effective:
- Short time window for valid timestamps (e.g. 2–5 minutes).
- Persistent storage of used nonces/event IDs for the duration of the time window.
- Idempotent processing via event ID checks.
- Detection of multiple deliveries: differentiated logging levels (warning vs. error).
In a self‑hosted environment like Affilentra you can store nonce caches in Redis or the database with TTL; the important thing is that storage is fast enough to check parallel requests consistently.
Verification and Error Handling
Error cases should be transparent and manageable:
- On signature errors: 401 Unauthorized + logging with request ID, but without payload content in logs if sensitive data is involved.
- On timestamp/nonce errors: 400 Bad Request with a clear error description in the body.
- On repeated deliveries: 200 OK if the event was already processed, and return an indicator, e.g. {"status":"duplicate","event_id":...}.
- Alerting: on an unusually high rate of signature or timestamp errors: automatic alerts to operators and merchants.
Operational Recommendations & Secret Management
Role‑based administration is central in Affilentra: platform operators manage the software, merchants configure integration secrets, partners use dedicated keys. Recommended measures:
- One separate secret per integration; do not reuse secrets.
- Store secrets in environment variables or secret stores (e.g. HashiCorp Vault); never in code or public repositories.
- Regular key rotation (e.g. every 90 days) with a transition phase that accepts both old and new keys.
- Audit logs for key usage and rotations.
- Restrict IP access to webhook endpoints where possible (whitelist) — as a supplement, not a replacement for signatures.
Practical example: HMAC‑SHA256 flow (conceptual)
This is how a minimal signature workflow in Affilentra can look:
- Sender: generates timestamp, raw_body and nonce; signature = HMAC‑SHA256(timestamp + '.' + raw_body, shared_secret).
- Sender: sends POST to recipient with headers X‑Affilentra‑Timestamp, X‑Affilentra‑Nonce, X‑Affilentra‑Signature and raw_body.
- Recipient (Affilentra): verifies TLS, reads raw_body, checks timestamp against system time, checks nonce cache, computes HMAC and compares signatures in constant time, validates event_id and processes idempotently.
These steps are intentionally kept simple; in implementation you should ensure constant-time comparisons, secure random nonces and robust error logs.
Role-specific notes for Affilentra users
- Merchants: Create separate secrets per payout provider and accounting tool. Use Affilentra configurations to enforce signature requirements.
- Network operators: Provide centralized monitoring and require integrity-checking headers from partners. Use the PRO & NETWORK Editions for granular permission management.
- Partners/Publishers: Verify outgoing Affilentra webhooks locally before further processing and document expected headers and event IDs.
Conclusion and next step
Operating webhooks securely requires consistent application of signatures, replay protection and operational controls. In the self-hosted Affilentra platform you can configure these mechanisms by role to reliably secure integrations with payout providers, accounting tools and partner systems. If you are looking for a secure, self-hosted solution with a perpetual license and no revenue sharing, consider the PRO & NETWORK Editions.
Act now: Choose your entry point and learn how Affilentra robustly secures your webhook integrations: https://affilentra.de
Next step
Try Affilentra yourself
Unified platform that transparently brings together product provisioning, tracking, conversion validation, commission calculation and payout across clearly separated roles; option for self-hosted installation with a perpetual license without revenue sharing; merchants retain control over products, terms and creatives; partners receive personal tracking links and a transparent payout history.