Webhooks

ONVO uses webhooks to notify your application when a result is produced while processing a payment intent, subscription, checkout session, or incoming transfer.

To receive them, configure a callback URL in your ONVO account. ONVO sends a POST request to that URL whenever a supported event is processed. The payload includes a type attribute that identifies the event and a data object with the related information.

Related API reference

• Payment intents
• Subscriptions
• Checkout sessions
• SINPE Movil

Recommended flow

1. Expose an HTTPS endpoint.
2. Register the endpoint in the ONVO Dashboard under developers.
3. Verify the event origin with the webhook secret.
4. Process the event idempotently.
5. Respond with a 2xx status when processing succeeds.

Supported events

Event	When it happens
payment-intent.succeeded	A payment intent is processed successfully.
payment-intent.failed	A payment intent fails.
payment-intent.deferred	A payment intent is waiting for approval, for example in a SINPE flow.
subscription.renewal.succeeded	A subscription renews successfully.
subscription.renewal.failed	A subscription renewal fails.
checkout-session.succeeded	A checkout session is processed successfully.
mobile-transfer.received	An incoming transfer is received on a custom SINPE Movil number.

mobile-transfer.received is an additional notification for merchants with this capability enabled. It does not represent a successful payment by itself and is not sent by default. Contact support to enable it.

Security

Each webhook has an assigned secret. You can view it in the ONVO Dashboard next to the webhook configuration.

ONVO includes that value in the X-Webhook-Secret header. The backend generates secrets with the webhook_secret_ prefix. Use it to verify that the request comes from ONVO before processing the event.

X-Webhook-Secret: webhook_secret_...

Responses and errors

When an event represents an error, the payload object can include an error attribute. That object can contain:

Field	Description
message	Human-readable error description.
code	Error code, when available.
type	Error type, when available.

Your endpoint should respond with a 2xx status only when the event was received and processed correctly. If you respond with another status, ONVO may retry the delivery.

Your system should tolerate retries and events received out of order.