Webhooks

Webhooks can be used as alerts to keep your systems and partner applications in sync with actions in Skipify.

Overview

Skipify can send outbound webhooks to any publicly accessible server. When an event is triggered (e.g. a PayLink URL has become inactive), Skipify will send a webhook notification to the endpoint(s) you specify in the Merchant Portal and await a response from your server(s) confirming receipt. The payload from the webhook will contain the unique orderId or paymentRequestId so that you can lookup the order or payment request and update your records as necessary.

📘

Implementation Tip

If you would like to generate a test server URL you can do this using RequestBin or Mockbin. We do not recommend using this for production traffic, only in our pre-production environments.

Merchant Portal Setup

In order to configure webhooks within Skipify, log into the Merchant Portal. When you arrive at the Webhooks section, you will be able to create or remove webhook endpoint configurations.

On this page you will be asked to specify:

  • The endpoint to which you'd like the webhook sent
  • The event(s) to which you would like to subscribe
  • The email to notify when a webhook has not been sent successfully
  • A description of the purpose of this integration
  • An encryption secret which you can specify to trust that the webhook came from Skipify
917

Event Types

Skipify can send the following notifications to your systems:

  • ORDER_PAYMENT_SUCCEEDED - sent when a consumer has a successful authorization on an order (applicable to any use case)
  • ORDER_PAYMENT_FAILED - sent when a consumer has a failed payment authorization (applicable to any use case)
  • PAYMENT_REQUEST_EXPIRED - sent when a PayLink payment request is no longer valid for a consumer to make a purchase

🚧

Implementing Webhooks

After you set up your webhook endpoint, reach out to your implementation specialist to confirm that it has been set up correctly and is receiving messages.

Webhook Request and Response

Webhook event requests are sent via POST requests to the URL(s) you specify. When a webhook event is triggered, you will receive a request with event details. Below are example request bodies for ORDER_PAYMENT_SUCCEEDED, ORDER_PAYMENT_FAILED, and PAYMENT_REQUEST_EXPIRED events:

// Sample for ORDER_PAYMENT_SUCCEEDED:
{
 eventName: "ORDER_PAYMENT_SUCCEEDED", // The event that triggered the webhook
 merchantId: "a82bcdf5g-0a5f-4462-cdf5-2ccee61eef61", // The merchantId that the event was triggered for
 partnerMerchantId: null, // The partner merchantId, if it exists
 payload: { // Specific info for the event
     orderId: "5fcyt67h-0a5f-4462-ef67-2ccee61eef61", // The GoCart order ID
     merchantOrderId: "74fhgit9a", // The merchant's order ID
     amount: 661, // The amount in cents that the order was for
     gatewayTransactionId: "33025612368456520", // The gateway transaction ID
     completedAt: "2022-03-22T15:45:06.7233073+00:00" // Timestamp the order was completed at
 },
 manualRetryId: null, // Id of the manual retry if it was performed via Merchant Portal
 secret: "yoursupersecret", // Secret that was set on the Webhook subscription if applicable
}

// Sample for ORDER_PAYMENT_FAILED:
{
 eventName: "ORDER_PAYMENT_FAILED", // The event that triggered the webhook
 merchantId: "a82bcdf5g-0a5f-4462-cdf5-2ccee61eef61", // The merchantId that the event was triggered for
 partnerMerchantId: null, // The partner merchantId, if it exists
 payload: { // Specific info for the event
     orderId: "5fcyt67h-0a5f-4462-ef67-2ccee61eef61", // The GoCart order ID
     merchantOrderId: "74fhgit9a", // The merchant's order ID
     amount: 661, // The amount in cents that the order was for
     gatewayTransactionId: null,
     completedAt: null
 },
 manualRetryId: null, // Id of the manual retry if it was performed via Merchant Portal
 secret: "yoursupersecret", // Secret that was set on the Webhook subscription if applicable
}

// Sample for PAYMENT_REQUEST_EXPIRED:
{
 eventName: "PAYMENT_REQUEST_EXPIRED", // The event that triggered the webhook
 merchantId: "a82bcdf5g-0a5f-4462-cdf5-2ccee61eef61", // The merchantId that the event was triggered for
 partnerMerchantId: null, // The partner merchantId, if it exists
 payload: { // Specific info for the event
     paymentRequestId: "4d147660-5391-4e01-afaa-c11c8ee84fb4", // The GoCart payment request ID
     merchantPaymentRequestId: "517as3b0e1x", // The merchant's payment request ID
     amount: 230, // The amount in cents of the payment request
     expiration: "2022-03-18T17:18:40.8900405+00:00" // Timestamp of when the payment request expired
 },
 manualRetryId: null, // Id of the manual retry if it was performed via Merchant Portal
 secret: "yoursupersecret", // Secret that was set on the Webhook subscription if applicable
}

Skipify only considers a notification delivered if it receives a timely response with a successful status code. These conditions must be met:

  • Your endpoint must be reachable at port 443 (HTTPS) (Skipify does not support other ports).
  • Your endpoint must respond within 5 seconds
  • Your endpoint must respond with a 2XX status code (e.g. 200, 201, 204, etc). Skipify does not follow redirects or consider them successful responses.

Failures and Retries
1421

You can use the Webhook page in the admin portal to view individual webhooks which have been sent, as well as retry failed webhooks.

Each failed webhook attempt will be retried 3 times over the course of 12 hours. Administrators on the Skipify merchant account will receive an email notification each time a webhook fails to send (at the end of the 12 hour retry window).

After the retry window, the webhook can be manually retried via the Admin portal UI for a period of 30 days, after which the webhook will not be able to be retried again.


Updated 5 months ago