Webhooks overview

Webhooks allow apps, or custom Storefronts, to stay in sync with Shopery data or perform an action after a specific event occurs. Webhooks are a performant alternative to continously polling for changes to data.

For example, a webhook can notify your internal systems when order is performed, and generate actions according your business logic.

Use cases

Common webhooks use cases include the following:

• Collecting data for data warehousing
• Integrating with accounting software
• Filtering order items and informing shipping companies about orders

Webhook concepts

To help orient you with the content of this helping guide, let's break this into concepts:

Webhook: A single event message. Shopery can send a webhook to an endpoint. A webhook contains a JSON payload in the body and some metadata in the headers.

Webhook Event: An event controls when webhooks are created and what's in the webhook payload. For example orders-created webhook sends whenever an order is created and contain the order as the payload.

Webhook headers

In addition to the message payload, each webhook message has a variety of headers containing additional context.

‍

HTTP Header                         UseX

X-Shopery-Secret   Our awesome secret

Testing webhooks

You can test your webhook configuration by triggering the webhook. You can trigger webhooks in the following ways:

• Manually, using the Test URL button while configuring your webhook.
• By performing the related action.

Next steps

• Learn about webhook best practices, including how to respond quickly to webhooks, track failures, recover webhooks, and more.
• Learn how to configure your app to use webhooks.

Webhook best practices

The following guide describes some best practices for working with webhooks.

Respond quickly

After receiving a webhook using an HTTPS endpoint, it's important to respond to the request with a 200 OK within one to two seconds. There's a five-second timeout for the entire request, and the webhook delivery system expects to establish the connection in less than one second or the request times out.

Optimize connection management

The webhook delivery system uses HTTP Keep-Alive to reuse connections to the same host and endpoint. This reduces network congestion and the latency in subsequent requests. Ensure that you have Keep-Alive enabled for your endpoint to reduce the overhead of receiving concurrent requests.

Prepare your endpoint for a burst of requests

To prepare your endpoint for a burst of requests, decouple webhook processing from request responses. A common pattern is to store the payload in a message queue for later processing by a background worker. This reduces the chance of the request timing out and having the webhook delivery count as a failure. Storing the webhook and responding immediately ensures that your system is resilient to a high volume of requests.

Manage delays

In rare circumstances, you might experience delays receiving webhooks. However, webhooks are always sent with the most recent data for the given resource. The payload of the delivered webhook should reflect the most recent attributes for the resource between the time of the webhook's trigger and the webhook's eventual delivery.

If receiving webhooks up to a day late might cause issues in your systems, then we recommend comparing the timestamp of the webhook to the current date and time.

Track failures

Use delivery metrics to track any failed webhook deliveries and fix them before they affect users.

Avoid debounces

When you use the fields parameter to specify which fields should be sent by a webhook, include a field that always has a unique value. For example, you can include the updated_at field in the fields parameter.

Including a field that always has a unique value prevents the webhook from being dropped as a duplicate, such as in cases when only the id field is requested.

Ignore duplicates

Although the webhooks API is designed to minimize duplicate webhook events, it is still possible to receive the same event more than once. Your app should handle webhook events using idempotent operations; that is, receiving the same webhook event a second time in a row should have no additional effect. You can detect duplicate webhook events by comparing the payload directly to the previous state.

Use supported filter parameters

Most query endpoints support both the created_at_min and updated_at_min filter parameters. These filters can be used to build a job that fetches all resources that have been created or updated since the last time the job ran.

Build a scalable and reliable system

Tracking traffic from Shopery's platform can be overwhelming, especially as you grow.

If you need to manage large volumes of event notifications to build a scalable and reliable system, then you can configure subscriptions to send webhooks to Amazon EventBridge and Google Cloud Pub/Sub rather than through HTTPS.

Webhooks configuration overview

Shopery can send webhooks events throught HTTPS, more methods will come in the future.

Requeriments

• You are familiar with how webhooks work
• You're authenticated and have a valid JWT Token
• You've the required permissions

Webhook configuration flow

To recieve webhooks, complete the following steps.

• Create an endpoint of your choice to recieve events that are published
• Use our API Rest or use our UI to create a webhook that uses the endpoint as its destination.

HTTPS

This tutorial explains how to configure, test, and verify webhook endpoints of type HTTPS.

Step 1: Have your endpoint ready

Your endpoint must be an HTTPS webhook address with a valid SSL certificate that can correctly process event notifications.

Payloads contain JSON with the data for the webhook events.

Step 2: Create a webhook

You can create your webhook using the UI or using our API REST.

Creating a webhook using UI

• Login in the backoffice with a user with sufficient privileges.
• Go to Settings -> Webhooks
• Click on Create Webhook
• Fill the fields with the following information:
  • Webhook Name: A name that can help you identify that webhook
  • URL: Your endpoint where the payload will be send
  • Events: Which events should trigger that webhook

HTTP  Method  : POST

Endpoint    : https://api.shopery.app/company/webhooks

Headers            : Content-Type: application/jsonAuthorization: Bearer <jwt-token>X-tenant-ID: <your-tenant-id>

‍

Name                  Type                    Description

name                 String              Mane of the webhook

url                      String              URL of your endpoint

events               []                      List of events for subscribing

isEnabled         Bool                  If the webhook is enabled or not

Payload example

Here's an example of a body payload for creating a webhook using the Shopery API:

{
  "name": "webhook test",
  "url": "https://test.com/wh",
  "events": [
    "order-created"
  ],
  "isEnabled": true
}

API Response

Upon a successful request, you will receive a response from the API containing an id field. This indicates that the import has been accepted and is being processed.

{
  "id": "wbh_01HA4XCG60CT4G3EWF4CKYM1MF"
}

Step 3: Test the webhook

You can test the webhook, using the Test URL button in webhook configuration, this will try to connect to your endpoint and will expect a HTTP 200 status code.

Step 4: Verifying the webhook

Before you respond to a webhook, you need to verify that the webhook was sent from Shopery, you can verify this using Endpoint Secret

Each petition from Shopery servers to your endpoint will cointain this Signature, your app should make sure that the Signature sended and the one configured in Shopery are the same.

‍