Webhooks

Webhooks let your application react when something happens in SellApp, such as an order being completed or a support ticket receiving a new message.

Registering webhooks

To register a webhook, you need a URL in your application that SellApp can call. You can configure a new webhook from your storefront developers settings under the developers tab.

Add your callback URL, pick the events you want to listen for, and save the webhook. Whenever one of those events happens, SellApp will send a webhook request to your endpoint.

When your app receives a webhook request from SellApp, inspect the event attribute to see what triggered it. The first part of the event type tells you the payload category, such as an order or product.

Example webhook payload

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

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

Event types

Name: cash_app.payment_requires_attention
Description: A CashApp payment is pending.
Name: feedback.created
Description: A new feedback was created.
Name: order.created
Description: A new order was created.
Name: order.completed
Description: An existing order was paid.
Name: order.disputed
Description: A paid order was disputed.
Name: product.created
Description: A new product was created.
Name: product.updated
Description: An existing product was updated.
Name: product.trashed
Description: A product was successfully deleted.
Name: ticket_message.created
Description: A new ticket message was created.
Name: variant.created
Description: A new product variant was created.
Name: variant.updated
Description: An existing product variant was updated.
Name: variant.sold_out
Description: An existing product variant ran out of stock.

Example payload

{
  "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 verify that a webhook really came from SellApp and not from a malicious sender, validate the request signature. To create a webhook signing secret, navigate to your storefront developers settings, click New Secret, and save it.

Each webhook request contains a signature header. You can verify that signature by hashing the raw request payload with your secret webhook key using HMAC SHA-256.

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 the request came from SellApp. Keep your secret webhook key safe. If it leaks, you can no longer trust the signature.

Discord webhooks and email notifications

Traditional webhook delivery cannot be used to post directly into a Discord channel. Instead, go to your store notifications settings and configure your Discord webhook URL there.

Discord and email notification channels support the same types of events as traditional webhook events. For setup instructions, see the creating notifications guide.

Webhooks

Registering webhooks

Consuming webhooks

Event types

Security

Discord webhooks and email notifications

On this page