Overview
VPOS.am webhooks deliver payment, fiscal and reconciliation events with signatures, retries and idempotent handling requirements.
Minimum safe handler
The handler accepts the event, verifies the signature, stores the payload and event id, responds quickly and sends heavy business logic to a queue. This reduces timeout and repeated delivery risk.
Orders, invoices or customer states must not change before signature verification. If the signature is invalid, the event is rejected and recorded in the security log.
Retries and temporary failures
Repeated webhook delivery should not be an error for business logic. If the event id has already been processed, the handler returns a successful or safe current result without creating duplicate entities.
If CRM, ERP or fiscal service is unavailable, the event is stored and retried through a queue. The failure must be visible to operations instead of disappearing in server logs.
Which events should be separated
Payment events, fiscal events and reconciliation events should be handled separately. They have different consequences: one changes an order, another issues a receipt, the third creates a manual review task.
This makes the integration easier to understand for developers, operations and accounting.
FAQ
What must a webhook handler do before changing an order?
It must verify the signature, store the event id and payload, confirm that the event was not processed before and only then update orders, invoices, fiscal jobs or CRM status.
Why should heavy business logic go to a queue?
A webhook endpoint should respond quickly. A queue makes it possible to retry CRM, ERP, e-mail or fiscal actions after temporary failures without losing the event.