Guides

Webhooks

How Inspow receives payment events from the gateway and updates Invoices and Subscriptions.

Inspow receives payment events from the payment gateway through a webhook. When a transaction changes status, the gateway notifies Inspow, which verifies the authenticity of the event and updates the Invoice and, where applicable, the associated Subscription.

The endpoint

Events arrive at POST /api/payments/<gateway>/webhook, where <gateway> identifies the gateway adapter (for example /api/payments/wompi/webhook). It is a public endpoint (without a User session) and without Organization context, since the call comes from the gateway. Its path carries no version: it doesn’t change even as the API versioning advances. If the gateway doesn’t exist, it responds 404.

Signature verification

Before processing any data, Inspow validates the event’s signature with the gateway’s secret. If the signature is not valid, the request is rejected with 401 and no change is made.

Processed events

Each gateway translates its events into a common format. In the case of Wompi, the transaction.updated event is handled; any other event, or one without a reference or status, is acknowledged as received (200) but doesn’t generate changes.

The transaction status can be:

Status	Effect on the Invoice
`APPROVED`	It becomes paid (`PAID`): the payment date, the transaction identifier and the payment method are saved.
`DECLINED`	It becomes failed (`FAILED`) and the reason for the rejection is saved.
`VOIDED`	Payment voided after being approved: it goes back to pending (`PENDING`).
`PENDING`	Payment in progress (for example PSE): only the attempt is recorded.
`ERROR`	Acknowledged as received, with no changes to the Invoice.

Payment references

The transaction reference determines how the event is routed:

Reference	Handling
Starts with `ONB-`	Payment from the online sign-up: it is processed by the sign-up flow.
Any other	Payment of an Invoice (their references start with `INV-`).

Reaction to the event

For an Invoice payment, Inspow emits an internal event that the billing module listens to in order to update the Invoice. Internal errors are logged, but the response to the gateway is always 200 once the signature has been verified, so that it doesn’t retry endlessly.

When the first Invoice of a Subscription that was pending payment is paid, the subscription becomes active, which gives access to the Member/Student/Patient/Club member.