Webhooks

Let's look into how to register and consume webhooks to integrate your app with SellApp. With webhooks, your app can know when something happens in SellApp, such as someone placing an order or replying to a support ticket.

Registering webhooks

To register a new webhook, you need to have a URL in your app that SellApp can call. You can configure a new webhook from the SellApp storefront settings under the developers tab. Add your URL and pick the events you want to listen for, then save the webhook.

Now, whenever an event happens that you're subscribed to, a webhook is fired off by SellApp. In the next section, we'll take a look at how to consume webhooks.

Consuming webhooks

When your app receives a webhook request from SellApp, check the event attribute to see what event caused it. The first part of the event type will tell you the payload type, e.g., an order, product, etc.

{
  "event": "order.completed",
  "data": {
    "id": 236,
    // ...
  },
  "store": 1
}

In the example above, an order was completed, and the payload type is an order.

Event types

{
  "event": "ticket_message.created",
  "data": {
    "author": "CUSTOMER",
    "sender": "mark@meta.com",
    "content": "Hey, I'm interested in investing.",
    "ticket_id": 1337,
    "updated_at": "2022-04-20T13:37:69.000000Z",
    "created_at": "2022-04-20T13:37:69.000000Z",
    "id": 6969,
    "ticket": {
      "id": 1337,
      "title": "Acquisition",
      "status": "OPEN",
      "customer": {
        "id": "c4e45131-a187-3476-9efd-1fb6fbbf2243",
        "email": "mark@meta.com"
      },
      "reference": {
        "id": 87654,
        "type": "App\\Models\\Invoice"
      },
      "created_at": "2022-04-20T13:37:69.000000Z",
      "updated_at": "2022-04-20T13:37:69.000000Z",
      "store_id": 1,
      "read_by": 1,
      "archived": 0
    }
  },
  "store": 1
}

Security

To be certain that a webhook was, in fact, sent by SellApp instead of a malicious actor, you can verify the request signature. To create a webhook signature, navigate to your storefront's developers settings, click "New Secret", and then click save.

Each webhook request contains a header named signature, and you can verify this signature by using your secret webhook key generated above. The signature is an HMAC hash of the request payload hashed using your secret key. Here is an example of how to verify the signature in your app:

const signature = req.headers['signature']
const hash = crypto.createHmac('sha256', secret).update(payload).digest('hex')

if (hash === signature) {
  // Request has been verified
} else {
  // Request could not be verified
}

If your generated signature matches the signature header, you can be sure that the request was truly coming from SellApp. It's essential to keep your secret webhook key safe — otherwise, you can no longer be sure that a given webhook was sent by SellApp. Don't commit your secret webhook key to GitHub!

Please note that test webhook requests do not contain the signature header, nor can test events be verified using your signature. To test the signature, you will want to emulate a real webhook event.

Discord webhooks + email

You will not be able to use traditional webhook notifications to receive events in a specified channel on your Discord server. Instead, you will need to head on over to your store's notifications settings and set your Discord webhook URL there.

Discord/email notification channels support the same amount and type of events as traditional webhook events. For more information on how to set up notification channels, check our setup guide here.