Webhook Event Subscriptions

Stitch produces various events within our system. These events can provide information about asynchronous events such as refunds, payments, and other products.

To receive information about specific events, you can provide a URL which receives messages from the payment request events you choose.

No Extra Cost

Please note that the webhooks via Svix will be provided to your integration at no extra cost, and without requiring your own separate Svix account.

Creating a Subscription

To simplify the process of subscriptions, we only require 2 fields, as described in the table below:

Parameter	Required or Optional	Usage
url	Required	The endpoint Stitch will submit the subscription data via a POST request. Due to the sensitive nature of the data being transmitted, the url must use the HTTPS protocol.
filterTypes	Required	Allows specifying one or more of the events you wish to subscribe to. See the below section for more information on these types.

Event types

Depending on the product you are integrating, different event types may be applicable. These are explained below:

Type	Product Usage
payment	For all products that incorporate payment requests, including Pay by Bank, Capitec Pay, Card (Once-off), Manual EFT and Cash. This webhook will be sent on each payment request status update.
payment.confirmation	For all products that incorporate payment requests, and when a Stitch intermediary account is used, including Pay by Bank, Capitec Pay, Card (Once-off), Manual EFT and Cash. This will be sent whenever funds are received for the payment request, in the intermediary account.
payment-initiation	For the LinkPay product. This will be sent on each payment initiation status update.
payment-initiation.confirmation	For the LinkPay product, and when a Stitch intermediary account is used. This will be sent whenever funds are received for the payment initiation, in the intermediary account.
refund	For the Refunds product. This will be sent on each refund status update.
disbursement	For the Disbursements product. This will be sent on each disbursement status update.
settlement	For the Settlements product, when a Stitch intermediary account is used for payins. This will be sent on each settlement status update.
direct-deposit	For the Direct Deposits product, when a Stitch intermediary account is used for payins. This will be sent whenever funds are received for a direct deposit, in the intermediary account.
payment-consent-request	For recurring payin products, such as Card, and Debicheck. This will be sent on all initiated consent status updates.
transaction	For recurring payin products, such as Card, and Debicheck. This will be sent on all initiated transaction status updates.

Subscribing via Query

The below query can be used to create a webhook subscription. In the example, we're subscribing to the refund event type for our refunds product. You can also create and manage your webhook subscriptions via the Svix consumer portal.

Subscribing via the Consumer Portal

Svix provides a consumer portal to manage your webhooks. You can use it to:

• create new webhook subscription endpoints.
• modify existing subscription endpoints.
• view event types and their schema under the Event Catalog section.
• view events we have sent under the Logs section.
• retry failed events.
• rate limit requests to your webhook endpoint (will be specified as requests per second).
• add custom request headers to include as part of the webhook data sent to your endpoint.

To access this consumer portal, you can generate a single-use URL by running the query below with your client token.

Once you open the link in the response from the above query, you'll automatically be logged into the consumer portal. If you have one or more endpoints setup already, you'll get a list showing each endpoint's URL and the error rate.

Creating a Subscription

To add an endpoint via the Svix consumer portal, you'll still need the same simple request variables shown previously in the API approach. You'll provide a URL to receive the events and specify one or more event types you want to listen to on that URL.

Note that you can also additionally add a Description so that you get a helpful snippet of what the endpoint does on the main endpoint listing page

Svix Play

If you don't have an endpoint on your service ready to start receiving events just yet, just press the "use Svix Play button" in the above screenshot to have a unique URL generated for you.

You'll be able to view and inspect all operational webhooks sent to your Svix Play URL, making it effortless to get started.

Once you specify the two parameters ie URL and event types, click on "Create" to add the endpoint and take you to the details page where you can retrieve the signing secret as well as set up other useful details such as rate limiting and custom headers.

In the below example, we're listening to disbursement and refund events on a Svix play endpoint

Adding Custom Headers

Alongside the webhook event data itself, your application might also require certain custom headers bundled together with the webhook. A common example is adding authentication info if you expect a specific authentication header to be added to the webhook for security and facilitate authenticating the request once Svix send it to your endpoint.

Once you have created the endpoint, you can set one or more custom headers via the consumer portal under the endpoint's Advanced tab. Keeping with the endpoint we created before, the below section shows how to set a custom header key Authentication with the value authentication-details After you set the header key and value, click on the + icon to the right of the value to add it, and have it added to any new webhook events sent.

danger

Please note that only the values with Authorization for the header's key name will have their plaintext value hidden on the application portal. Any other key name will always have its value displayed in plaintext.

Consuming Webhook Events

After subscribing to an event, you will need to consume it. At its core, a webhook is a simple POST request with the body as the event. You could trust that any event sent to your publicly exposed endpoint is valid, but there is the possibility that anyone could send a message to that endpoint.

To combat this you can and should verify that the messages you receive are from Stitch and Svix. The underlying structure of the events has not changed from our legacy webhooks product, but the verification process has. A secret is provided by Svix that can be used for verification, and it is this secret what should be used to verify the Svix webhook signature.

The secret for each endpoint can be obtained from the application portal within it's details section on the right-hand sidebar, or from the response in the clientWebhookAdd mutation shown before. By default, it'll always be hidden on the application portal unless you click the eye icon on the right of the hidden value.

An example is given below for Node.js (Express), and uses the svix npm package, but various other popular languages are also supported. Please refer to the main Svix docs for more examples.

Use Raw Request Body

When passing the request body to the Svix verification function from your preferred framework, please ensure you use the raw request body. The cryptographic signature is sensitive to even the slightest changes, so any whitespace, carriage return etc. will break the signature verification.

You should watch out for frameworks that parse the request as JSON and then stringify it because this too will break the signature verification.

In the express sample below, we are using the Node JS body parsing middleware

// Taken from https://docs.svix.com/receiving/verifying-payloads/how#nodejs-express
import { Webhook } from "svix";
import bodyParser from "body-parser";

const secret = "YOUR_SVIX_SECRET_HERE";

app.post(
  "/webhook",
  bodyParser.raw({ type: "application/json" }),
  (req, res) => {
    const payload = req.body;
    const headers = req.headers;

    const wh = new Webhook(secret);
    let msg;
    try {
      msg = wh.verify(payload, headers);
    } catch (err) {
      res.status(400).json({
        message: err.toString(),
      });
    }

    // Do something with the message...

    res.json({
      message: "Webhook verified successfully",
    });
  },
);

Retry Policies

Svix attempts to deliver each webhook event, and should the request fail (the endpoint responds with a non-200 response), will retry based on a retry policy with exponential backoff. Each retry attempt per message is based on the following schedule, with each period starting immediately after the failure of the preceding attempt.

To read more about how Svix handles automated and manual retries, you can refer to the main guide from the Svix docs

Manually Replaying Events

The application portal can be used to manually retry each message (whether failed or successfully sent) at any time, or all messages within a given date or time frame. The following time frames are available on Svix for resending failed messages:

• 8 hours
• Yesterday
• 3 days
• Last week
• 2 weeks ago

Retention Period

Please note that Svix retains all the message payloads for a period of 90 days. Afterwards they are deleted to ensure potentially sensitive and private information is not held indefinitely.

List Webhook Endpoints

To list your webhook endpoints using our API, you can run a simple GraphQL query. This returns all urls subscribed to an event.

tip

Excluding the filter parameter returns all webhook types currently subscribed to for your client

The second way to list the endpoint is to use the SVIX dashboard and look at which endpoints exist.

Migrating to Svix

info

This is only needed for clients already using our legacy webhook subscriptions and would wish to start receiving them from Svix.

To move from receiving Webhooks directly from us and receive them from Svix, there is a Graphql Mutation you can run. If you run the mutation clientSubscriptionMigrate and provide the ID of the existing subscription then we will start sending messages through Svix.

Warning

After running the migrate command your consumed events could fail verification. They will initially fail until you update the verification process. When it has been updated you can log in to the Svix dashboard and replay failed messages.

Another method you can use to migrate is to create a new URL that handles Svix messages and subscribe to both messages at once and then stop the old subscription once the Svix messages are being handled correctly.

Deleting a Subscription

To unsubscribe or remove a webhook you can run the clientWebhookDelete mutation. Here you have the option of unsubscribing to a specific event type by providing a filterTypes input. If you wish to delete the entire endpoint then you can omit the filterTypes entirely.

Other Useful Information

Whitelisting Source IPs

In case your webhook endpoint is behind a firewall or NAT, you'll need to allow traffic from Svix's IP addresses. You can refer to the full list of IP addresses in the Svix docs.

Secret Rotation

Should your Svix secret ever be compromised (whether confirmed or suspected), it needs to be rotated to ensure security of the signature verification process and your transactions.

Once you're on the details page of the endpoint you want to rotate, click on the dropdown in the top right corner of the current signing secret, then select the Rotate Secret option from the dropdown menu. Once you confirm on the dialog box that pops up, you'll get a new secret which can be used for signature verification, as shown in this section previously

If you're using one of the Svix SDKs for signature verification, it'll automatically take care of signature verification with the new secret.