Event Webhook 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 events you choose.

Creating a Subscription

To simplify the process of subscriptions, we only require 2 fields. The event you wish to listen to, and the URL that is set up to receive webhooks

These 2 parameters are explained in the below table:

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 of the events you wish to subscribe to. Valid events are refund, payment, payment.confirmation, payment-initiation, payment-initiation.confirmation, disbursement

Open in IDE ↗

Managing Webhooks

There is a dashboard to manage your webhooks. You can use it to view event types and their schema, modify existing subscription endpoints, view events we have sent, and even retry failed events.

To get to the dashboard, you can generate a single-use URL by running the query below with your client token.

Open in IDE ↗

Consuming an Incoming Webhook Event

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. To do this you can follow the documentation at Svix

The underlying structure of the events has not changed, but the verification process has. A secret is provided by Svix that can be used for verification. The documentation is linked above.

An example is given below for Node.js (Express)

import { Webhook } from "svix";
import bodyParser from "body-parser";

const secret = "YOUR 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({});
    }

    // Do something with the message...

    res.json({});
  }
);
// Taken from https://docs.svix.com/receiving/verifying-payloads/how#nodejs-express

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

Open in IDE ↗

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

Migrating Webhook Subscriptions to 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.

Open in IDE ↗

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.

Open in IDE ↗