What are webhooks?

A webhook sends an event from Instant to one of your own systems at the moment the event happens. An event is something Instant did or something a shopper did, such as an email that Instant sent or a product that a shopper added to their cart.

Why you need them

  • Your other systems, such as a call centre tool, an ERP or a data warehouse, do not know what happens in Instant unless something sends it to them.
  • Without webhooks, the only way to move this data is to export it and import it by hand.
  • Each system only needs some events. With webhooks, you choose the events that each system receives.

How to set it up

Before you start

  • You need a developer. Your system must have a public URL that starts with https:// and can receive the events. Everything your developer needs is in the Instant API Reference, in the Webhooks section.
  • You need to be a site admin to add or change a webhook.
  • Webhooks belong to an app in Your apps. An app holds the credentials and permissions for one of your systems. If you do not have an app for this system yet, create one first.

Creating an app

Skip this section if you already have an app for this system.

  1. Click the Settings cog in the bottom left corner of your Instant dashboard.
  2. Under Site, select Integrations.
  3. Under Your apps, click Create app.
  4. Enter an App name, such as the name of the system.
  5. Choose a Connection method. Token exchange is the recommended option.
  6. Click Create app.

Turning on the permissions

  1. Go to Integrations and, under Your apps, open your app.
  2. In Permissions, turn on Events · Read.
  3. Turn on Profiles · Read.

Note: You cannot add an endpoint until both permissions are on.

Adding an endpoint

An endpoint is the URL of your system that receives the events.

  1. On the app’s page, in Webhooks, click Add endpoint.
  2. In Endpoint URL, enter the URL that your developer gave you.
  3. In Description (optional), enter a short name for the system, such as “Call centre”.
  4. Under Events to send, select the events that this system needs.
  5. Click Save endpoint.

Instant starts sending the selected events as soon as you save the endpoint.

Sending a test event

  1. In Webhooks, click the endpoint to open it.
  2. Next to Signing secret, click Reveal.
  3. Copy the secret and give it to your developer. Your system uses it to check that each event came from Instant.
  4. Click Send test event.
  5. In Event, choose an event.
  6. Click Send.

The result shows Delivered or Not delivered, with the response from your system and the time it took.

Tip: A test event has the same format as a real one, and is marked as a test. Your developer can use it to build and check the receiver before real events arrive.

How it works

Events you can send

Event When Instant sends it
Email Sent Instant sent an email.
Email Delivered An email was delivered.
Email Opened A shopper opened an email.
Email Clicked A shopper clicked a link in an email.
Email Bounced An email bounced.
Email Unsubscribed A shopper unsubscribed from email.
SMS Sent Instant sent an SMS.
SMS Delivered An SMS was delivered.
SMS Clicked A shopper clicked a link in an SMS.
SMS Unsubscribed A shopper unsubscribed from SMS.
Sign-up Form Submitted A shopper submitted an Instant sign-up form.
Product Viewed A shopper viewed a product.
Collection Viewed A shopper viewed a collection.
Search Submitted A shopper searched the store.
Item Added to Cart A shopper added a product to their cart.
Item Removed from Cart A shopper removed a product from their cart.
Cart Viewed A shopper viewed their cart.
Checkout Started A shopper started a checkout.
Checkout Contact Info Added A shopper added contact details in checkout.
Checkout Address Added A shopper added an address in checkout.
Checkout Payment Info Added A shopper added payment details in checkout.

What each event contains

  • The event type and the time it happened.
  • The details of the event. For example, an email event includes the flow or campaign, the subject line and the coupon code.
  • The shopper’s Instant profile ID, email address and phone number.

Instant only sends events for identified shoppers. Instant never sends a shopper’s browser details, such as their IP address.

Delivery and retries

  • Instant sends each event once to each endpoint that is subscribed to it.
  • An endpoint receives events from the time you add it. Instant does not send events from before that time.
  • If your system does not accept an event, Instant tries again after 1 minute, 5 minutes, 15 minutes, 30 minutes, 1 hour and 2 hours.
  • Your system can sometimes receive the same event twice, or receive events out of order. The API Reference tells your developer how to handle both.

Checking deliveries

Click an endpoint to see its Deliveries. The list shows the 100 newest attempts from the last 7 days. Each attempt is Delivered, Retrying or Failed.

Endpoint statuses

  • Active: deliveries work.
  • Failing: at least 90% of the attempts in the last hour failed, across at least 5 attempts. While an endpoint is failing, Instant sends each new event once, with no retries.
  • Turned off by Instant: the endpoint was failing for 2 days, so Instant turned it off.
  • Off: someone on your team turned the endpoint off.

To turn an endpoint on or off, open the endpoint, click the three dots, then select Turn on or Turn off.

Note: If Instant turned off your endpoint, fix your system first. Then send a test event, and turn the endpoint on when the test is delivered.

Changing the signing secret

To replace the signing secret, open the endpoint and click Roll secret. In Current secret expires, choose how long the old secret keeps working: Now, In 1 hour, In 24 hours or In 7 days. Until the old secret expires, Instant signs each event with both secrets, so your developer can update your system first.

FAQ

Do I need a developer to use webhooks? Yes. Your system needs a public URL that can receive the events and check the signing secret. The dashboard steps in this article do not need code.

Can I send events to more than one system? Yes. Add one endpoint for each system, and choose the events that each endpoint receives.

Will I receive events from before I added the endpoint? No. An endpoint only receives events that happen after you add it.

Can I receive order events? No. The table in this article is the full list of events that webhooks can send.

Does Instant send events for anonymous visitors? No. Instant only sends events for shoppers it has identified.

Why did Instant turn off my endpoint? Most of its deliveries failed for 2 days. Fix your system, send a test event, then turn the endpoint on again.

What happens to events that failed while my system was down? Instant retries each failed event for a few hours, on the schedule in this article. After the last retry, Instant does not send that event again.

What happens when I delete an endpoint? Instant stops sending events to it at once and drops any retries that were waiting. You cannot undo this.

What happens if I pause the app? A paused app sends nothing. Its endpoints do not receive events until you resume the app.


For the event formats, signature checks and code examples, see the Instant API Reference.