Introduction
Webhooks are the backbone of modern integrations: they power real‑time automation, reduce manual work and increase transparency between merchants, partners and billing systems. For operators of affiliate programs, reliable synchronization of conversion events, payout preparation and payout execution is especially critical. This article demonstrates practical webhook workflows with Affilentra — including payload templates and integration notes for accounting systems, payment providers and internal ERP systems.
Why Webhooks with Affilentra?
Affilentra provides a self‑hosted affiliate platform with clearly separated roles (software operator, merchant, partner). Webhooks allow events from the affiliate program to be delivered automatically to external systems here: validated conversions, prepared payout lists and status updates. Thanks to the self‑hosted architecture, merchants retain data sovereignty and can operate webhook endpoints themselves or integrate them into existing middleware.
Key Event Types and Their Uses
The following events form the basis for practical workflows:
- conversion.created – a tracking event was recorded and validated.
- conversion.updated – status changes (e.g., chargeback, refund, confirmed conversion).
- payout.prepared – a payout list or payout entry was created for accounting.
- payout.paid – payout was transmitted to the payment provider or marked as paid.
- accounting.export_ready – accounting‑relevant data is ready for export (e.g., as a booking entry or CSV).
- erp.update_required – status change that must be reflected in the internal ERP system (e.g., fulfillment or invoice status).
Payload Templates (Examples)
The following payloads are intended as templates for integration. Adjust fields to your internal schema and process only the fields you require.
conversion.created (Example)
{
"event": "conversion.created",
"timestamp": "2026-11-04T10:15:30Z",
"conversion": {
"id": "conv_12345",
"merchant_id": "m_987",
"partner_id": "p_456",
"offer_id": "o_22",
"amount": 149.90,
"currency": "EUR",
"status": "pending_validation",
"meta": { "order_ref": "ORD-20261104-001" }
}
}
payout.prepared (Example)
{
"event": "payout.prepared",
"timestamp": "2026-11-04T11:00:00Z",
"payout": {
"id": "po_20261104_01",
"merchant_id": "m_987",
"partner_id": "p_456",
"gross_amount": 320.00,
"fees": 5.00,
"net_amount": 315.00,
"currency": "EUR",
"payout_method": "bank_transfer",
"batch_id": "batch_20261104",
"entries": [ { "conversion_id": "conv_12345", "amount": 120.00 }, { "conversion_id": "conv_12346", "amount": 200.00 } ]
}
}
payout.paid (example)
{
"event": "payout.paid",
"timestamp": "2026-11-04T12:30:00Z",
"payout": {
"id": "po_20261104_01",
"paid_at": "2026-11-04T12:28:00Z",
"transaction_id": "txn_7890",
"provider_status": "settled"
}
}
accounting.export_ready (example)
{
"event": "accounting.export_ready",
"timestamp": "2026-11-04T12:35:00Z",
"export": {
"id": "exp_20261104_01",
"format": "csv",
"records": [ { "account_code": "8400", "debit": 0, "credit": 315.00, "description": "Affiliate Payout" } ]
}
}
Typical integration workflows
1) Conversion → Accounting preparation
Workflow: conversion.created → conversion.updated (confirmed) → accounting.export_ready.
- On conversion.created: store a minimal record in the middleware, perform validations (e.g., duplicates, CVR/order references).
- On conversion.updated with status confirmed: create accounting entries (accounts receivable, revenue, VAT) or mark the conversion for inclusion in the next export.
- On accounting.export_ready: generate CSV/DATEV/JSON and place it in the accounting directory or send it via SFTP to your tax consultant.
2) Payout preparation → Payment provider
Workflow: payout.prepared → Payment Provider API → payout.paid.
- payout.prepared: create a batch with payout entries, check limits and availability (balance, KYC status).
- Send the batch to your payment provider; use idempotent calls and provide the batch_id as reference.
- Receive feedback from the provider, mark transactions and wait for the payout.paid event for final posting.
3) ERP synchronization for fulfillment and invoice status
Workflow: conversion.updated / erp.update_required → ERP API.
- On status changes (e.g., fulfilled, refunded) Affilentra sends an erp.update_required event.
- Mapping: external_reference → ERP order number; update fulfillment status, invoice numbers and payment status.
- Best practices: use batch acknowledgements, rate limiting and verify references for uniqueness.
Best practices for robust integrations
- Security: Sign webhook payloads with HMAC (SHA256) and verify timestamps to prevent replay attacks.
- Idempotence: Process the same event ID multiple times without side effects. Use dedicated idempotency keys.
- Error handling: Implement retry logic with exponential backoff; centrally log failed deliveries.
- Versioning: Introduce an event schema version field to keep schema changes compatible.
- Batching: Send aggregated events for accounting and payouts (e.g. batch_id) to reduce effort and latency.
- Data minimization: Send only the fields target systems need; optionally offload additional metadata.
- Monitoring: Monitor delivery rates, latency and error rates; notify responsible parties in case of outages.
Role‑oriented notes
- Merchant: Define webhook endpoints, choose events and specify payout methods. Self‑hosting enables full control over data flows.
- Partner (Publisher): Benefit from auditable tracking links and transparent payout status notifications that can be delivered via webhooks to dashboards or accounting tools.
- Software operator: Provide secure signatures, documentation and monitoring; offer templates and mapping examples for common accounting and payment providers.
Practical examples: Implementation steps
- Define the relevant events and a minimally required field set (e.g. conversion_id, amount, currency).
- Set up middleware or a small receiving service that validates webhooks, deduplicates them and routes them to target systems.
- Implement HMAC signatures and verify timestamps within a short window (e.g. 5 minutes).
- Test with simulated events: conversion.created → payout.prepared → payout.paid → accounting.export_ready.
- Document error codes and recovery processes for your finance and operations teams.
Conclusion and next step
With Affilentra, webhook workflows for conversion tracking, payout preparation and accounting exports can be implemented in a practical and secure way—especially in self‑hosted scenarios where control and data protection are central. The combination of clear event schemas, idempotent processing and controlled payout batches reduces manual effort and increases transparency for merchants and partners.
Ready to use webhooks in production? Choose a getting started option
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 share; merchants retain control over products, terms and promotional materials; partners receive personal tracking links and a traceable payout history.