Webhooks

Webhooks let you receive an HTTP notification when an event occurs in Back in Stock. We currently support two topics:

notification/sent - a customer has been sent a Back in Stock notification.
notification/created - a new notification request has been created.

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

Webhooks are available on the Pro plan.

Receiving a webhook

To receive a webhook, create a subscription from your Back in Stock dashboard:

Go to Settings → Webhooks & API.
Choose the topic: notification/sent or notification/created .
Enter the URL the webhook will be sent to.
Click Create webhook.
Enable the webhook with the On/Off toggle.

The URL you specify must:

Be publicly accessible over HTTPS (HTTP URLs are rejected).
Accept a POST request with a JSON body.
Return an HTTP 200 response (other 2xx codes are treated as failures).

The webhook is delivered shortly after the event. If your URL does not return a 200 response, delivery is retried several times with increasing delays. A webhook that consistently fails is automatically deactivated. If your webhooks stop arriving, check Settings → Webhooks & API - you can re-enable the subscription with the On/Off toggle once your endpoint is fixed.

Tip: a service like webhook.site makes it easy to inspect and debug webhook requests while you're developing.

Payload

A webhook is sent as a POST request in JSON format. Example body:

{
  "notification_id": 12345,
  "topic": "notification/sent",
  "timestamp": "2023-09-11T12:13:45Z",
  "channel": "email",
  "customer": {
    "email": "john@example.com",
    "sms": null
  },
  "quantity_required": 1,
  "customer_language": "en-GB",
  "customer_utc_offset": 14400,
  "created_at": "2023-09-09T14:33:10Z",
  "accepts_marketing": true,
  "product": {
    "product_id": 8339067207909,
    "product_title": "Black Tea",
    "variant_id": 44211925318693,
    "variant_title": "Small",
    "sku": null,
    "handle": "black-tea"
  }
}

Testing your webhook

After creating a webhook, click Send test payload to immediately send a sample webhook to your URL. The test payload includes the key "test": true so you can tell it apart from real events.

Verifying a webhook request

When your system receives a webhook, you should verify that it is a genuine request from Back in Stock. Calculate a signature from the raw request body and compare it to the value of the X-BIS-Signature header.

The signature is a Base64-encoded HMAC-SHA256 digest of the request body, using your API token (from Settings → Webhooks & API) as the secret. This is the same method Shopify uses for its webhooks. Example in Ruby:

require 'openssl'
require 'base64'

SHARED_SECRET = 'your_back_in_stock_api_token'

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

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

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

Note: if you reset your API token, webhook signatures are calculated with the new token from that point on - update your endpoint's copy of the secret at the same time.

Need more help?

If you need further information or want to provide feedback on webhooks, email backinstock-support@useamp.com.