Webhooks API

SeQura provides webhooks to automate some order life cycle events, it allows merchants who wishes to avoid performing the same changes in their own back-office system and in SeQura's web interface to integrate their system with an automated workflow. This document describes how to use webhooks and it's protocol.

Webhook configuration: In order to receive the life cycle events the merchant must include the required configuration in the order solicitation process, that configuration is a JSON object named events_webhook located on the merchant section of the order payload which includes a mandatory url attribute with the URL that seQura will POST the event request, checkout Order API for details.

Webhook events

Any webhook event will consist in a POST request to events_webhook.url using application/x-www-form-urlencoded as encoding in UTF-8. The default parameters for that requests are:

In case the merchant provides extra information in events_webhook.parameters, those parameters will be merged suffixed with m_, to avoid overwriting the default ones. Event types could also include extra information to the parameters.

E.g., with {"signature" => "K6hDNSwfcJjF+suAJqXAjA=="} as events_webhook.parameters and events_webhook.url being https://my.shop.tld/checkout/sequra-events/8765432 the request will be

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 to that request, each event type defines it's own protocol (look for the specific details below).

Note that seQura includes a specific User-Agent

If the merchant receives any unknown or unimplemented event type, it should respond with a 501 Not Implemented plus a JSON that should look like this one:

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

Protocol definition

SeQura expects an empty response.

• Expected response status values are 200, 201, 202, 302, 307, 404 and 501. Other values will be considered errors.
• In case seQura considers the response as an error, the notification will be retried.

1. Cancellation notification (cancelled event)

When an order on hold (not yet confirmed) is rejected, seQura will cancel it and send a notification. It doesn't expect any action in the merchant side.

The event key for this request is cancelled.

Protocol definition

SeQura expects an empty response. This event is informative: the shop may use it to cancel orders that are on hold, and/or use it to recover the cart and tell the shopper to use an alternative payment method.

• Expected response status values are 200, 201, 202, 302, 307, 404 and 501. Other values will be considered errors.
• In case seQura considers the response as an error, the notification will be retried.

2. Cancellation requests (cancel event)

In the rare instances an order needs to be cancelled after the order has been confirmed, seQura will request the cancellation to the merchant.

The event key for this requests is cancel and an extra attribute is added to the default parameters, cancellation_request_url which is a link to seQura back office's page where operators can process the cancellation requests manually.

Protocol definition

SeQura expects a JSON response to that request which should include a result attribute, the accepted result values are:

• Expected response status values are 200, 201, 202, 302, 307 and 501. Other values will be considered errors.
• Any response that cannot be parsed as JSON will be considered an error.
• In case seQura considers the response as an error, the requests will be retried for a maximum of a week.

Note 1. If an order is manually cancelled through the interface or Order Update API the request process will be stopped

Note 2. The configured timeout for this request is 30 seconds, any request that timeouts will be considered an error and will be retried.

Using the cancellation request webhook event in sandbox environment

In sandbox environments orders are not cancelled by operators, so to be able to test the webhook integration seQura provides the following alternative:

If the customer surnames is 'cancellation event' a cancellation webhook requests process will be started. The process will start after a pause that is determined by the day part in the shopper's date of birth according to this formula: (day-1) * 10 seconds.

3. Denial notification

When a solicitation is denied Timon will send a notification. It doesn't expect any action in the merchant side.

The event key for this requests is denied.

Protocol definition

SeQura expects an empty response.

• Expected response status values are 200, 201, 202, 302, 307, 404 and 501. Other values will be considered errors.
• In case seQura considers the response as an error, the notification will be retried.

4. Risk notification

When a FP1 order is confirmed, Simba will send a risk assessment notification with the assessment resolution so that the merchant can integrate this resolution in their order management system or take automatic actions depending on the risk_level.

The event key for this requests is risk_assessment and it includes a risk_level field with the risk assessment resolution which is one of the followings:

• low_risk: The risk of accepting the order is low and Sequra will cover the risk of the order.
• high_risk: The risk of accepting the order is high and Sequra will not cover the risk of the order.
• under_evaluation: Our system is still evaluating the risk of the order. Once Sequra finish the evaluation a new event will be send with low_risk or high_risk resolution.

Protocol definition

There isn't a protocol defined for this notification, seQura just expects a successful HTTP response.

• Expected response status values are 200, 201, 202, 302, 307, 404 and 501. Other values will be considered errors.
• In case seQura considers the response as an error, the notification will be retried.