Webhooks API

seQura provides webhooks to automate order lifecycle events, letting you integrate with an automated workflow instead of manually updating both your system and seQura's interface.

Webhook configuration: To receive lifecycle events, include an events_webhook JSON object in the merchant section of your order payload. It requires a url attribute—the URL where seQura will POST event requests. See Order API for details.

Webhook events

Each webhook event is a POST request to events_webhook.url using application/x-www-form-urlencoded encoding in UTF-8. Default parameters:

If you provide extra parameters in events_webhook.parameters, they're merged with a m_ prefix to avoid overwriting defaults. Event types may include additional parameters.

Example with {"signature" => "K6hDNSwfcJjF+suAJqXAjA=="} as events_webhook.parameters and events_webhook.url as https://my.shop.tld/checkout/sequra-events/8765432:

POST /checkout/sequra-events/8765432 HTTP/1.1
Host: my.shop.tld
Content-Type: application/x-www-form-urlencoded
Accept: application/json
User-Agent: seQura-Event/1.0 (www.sequra.es)

charset=UTF-8&utf8=%E2%88%9A&event=cancel&order_ref_1=QWER1234&order_ref_2=%22%22&order_ref=ca412138-0af6-4079-a92d-24f7a0ffb18a&m_signature=K6hDNSwfcJjF%2BsuAJqXAjA%3D%3D

seQura expects an application/json response. Each event type defines its own protocol (see details below).

Note: seQura includes a specific User-Agent.

For unknown or unimplemented event types, respond with 501 Not Implemented and JSON like:

{"error": "Unknown event 'event-name'"}

Protocol definition

seQura expects an empty response.

• Expected status codes: 200, 201, 202, 302, 307, 404, 501. Other values are treated as errors.
• Errors trigger a retry.

1. Cancellation notification (cancelled event)

When an order on hold is rejected, seQura cancels it and sends a notification. No action is required on your side.

Event key: cancelled

Protocol definition

seQura expects an empty response. This is informative: you can use it to cancel on-hold orders and/or recover the cart to offer the shopper alternative payment methods.

• Expected status codes: 200, 201, 202, 302, 307, 404, 501. Other values are treated as errors.
• Errors trigger a retry.

2. Cancellation requests (cancel event)

In rare cases where an order needs cancellation after confirmation, seQura requests the cancellation from you.

Event key: cancel

Extra parameter: cancellation_request_url—a link to seQura's back office where operators can manually process cancellation requests.

Protocol definition

seQura expects a JSON response with a result attribute. Accepted values:

• Expected status codes: 200, 201, 202, 302, 307, 501. Other values are treated as errors.
• Non-JSON responses are treated as errors.
• Errors trigger retries for up to a week.

Note 1: If you manually cancel via the interface or Order Update API, the request process stops.

Note 2: Timeout is 30 seconds. Timeouts are treated as errors and retried.

Testing in sandbox

In sandbox, orders aren't cancelled by operators. To test the webhook, use 'cancellation event' as the customer surname. The process starts after a pause: (day-1) * 10 seconds based on the shopper's birth date day.

3. Denial notification

When a solicitation is denied, seQura sends a notification. No action is required on your side.

Event key: denied

Protocol definition

seQura expects an empty response.

• Expected status codes: 200, 201, 202, 302, 307, 404, 501. Other values are treated as errors.
• Errors trigger a retry.

4. Risk notification

When an FP1 order is confirmed, seQura sends a risk assessment notification. You can integrate this into your order management system or take automatic actions based on risk_level.

Event key: risk_assessment

The risk_level field contains one of:

• low_risk: Low risk. seQura covers the order risk.
• high_risk: High risk. seQura will not cover the order risk.
• under_evaluation: Still evaluating. seQura will send another event with low_risk or high_risk once evaluation completes.

Protocol definition

seQura expects a successful HTTP response.

• Expected status codes: 200, 201, 202, 302, 307, 404, 501. Other values are treated as errors.
• Errors trigger a retry.