Webhooks

Webhooks allows you to receive a notification over HTTP when an event occurs. Currently we support the following topics:

• notification/sent - This event occurs after a customer has been sent a Back in Stock notification email.
• notification/create - This event happens when any notification is created.

Webhooks can be used to integrate Back in Stock with other communication channels you might use with your store. For example, you could receive a webhook when a customer is notified so you can display a notification to the customer in a mobile app. 

Webhooks are available to accounts on the Medium store, Large store, and Enterprise plans.

Receiving a webhook

To receive a webhook you’ll need to create a subscription in your Back in Stock account. 

1. From you Back in Stock dashboard choose Settings, Webhooks.
2. Choose the topic: notification/sent or notification/create.
3. Enter the URL where the webhook notification will be sent.
4. Hit Create Webhook.
5. Enable the webhook by tapping the ‘On/Off’ toggle switch.

The URL you specify should meet the following criteria:

• Is publicly accessible over HTTPS
• Accepts a POST request
• Returns a 200 OK response.

The webhook request will be delivered shortly after the event. If the URL does not return an HTTP 200 response, the webhook will be retried several times. A webhook that consistently fails to return a 200 response will be deactivated by the system.

Tip: RunScope offer a handy service called Request Captures which makes it easy to view and debug webhook requests. 

A webhook is sent as  POST request in JSON format. Here’s an example of the body of the request: 

{
  "notification_id": 12345,
  "topic": "notification/sent",
  "timestamp": "2023-09-11T12:13:45Z",
  "channel": "email",
  "customer": {
    "email": "[email protected]",
    "sms": null
  },
  "quantity_required": 1,
  "customer_language": "en-GB",
  "customer_utc_offset": 14400,
  "created_at": "2023-09-09T14:33:10Z",
  "product": {
    "product_id": 8339067207909,
    "product_title": "Black Tea",
    "variant_id": 44211925318693,
    "variant_title": "Small",
    "sku": null
  }
}

Testing your webhook

To test your webhook endpoint you can send a test payload. After creating a webhook click Send test payload button to immediately send a webhook payload. The payload for a test webhook includes the key test with the value true.

Verifying a webhook request

When your systems receives a webhook you should validate it to ensure it is a genuine request from Back in Stock. You can verify the authenticity by calculating a signature and comparing it to the signature contained in the ‘X-BIS-Signature’ header.

You will need your Back in Stock API key to calculate the signature. You can find your API key from your dashboard under Account, API.

The signature calculation uses the same method as a Shopify webhook request (example in Ruby):

SHARED_SECRET = 'your_back_in_stock_api_key'

def verify_webhook(data, signature)
  digest = OpenSSL::Digest::Digest.new('sha256')
  calculated_hmac = Base64.encode64(OpenSSL::HMAC.digest(digest, SHARED_SECRET, data)).strip
  calculated_hmac == signature
end

signature = request.headers['X-BIS-Signature']
data = request.body

if verify_webhook(data, signature)
  puts 'Verified'
else
  puts "Webhook signature doesn't match"
end