Use Webhooks

Webhooks allow your app to be notified of events that happen in a Weebly site. For example, your app can be notified when a site is published, store products get updated, or an order is created. You configure a callback URL and events are sent to that address using a POST request. You can use the information you receive from the webhook to get further information from the API.

In this topic:

Subscribe to Webhooks

Before you can use webhooks, you need to subscribe to the events, using the manifest. Set the callback URL (where the event notice should be sent) and an array of the events you want to be notified of.

Note: All URLs must use the HTTPS protocol. You will not be able to upload an app that uses HTTP.

​​Additionally, you need to set the scope needed for access to the webhook information. Scopes are used for the user to grant permission to that access.

For example, if you want to be notified when a payment happens and when a site is updated, you'd set something like this in the manifest (read the manifest topic for comprehensive placement and syntax info):

Subscribe to Webhooks

Next, use the OAuth process to get a token to use for webhooks. Follow the steps here.

Note: We also offer a webhook API that allows you to programmatically read, add, delete, and update webhooks. Best practice is to set default webhooks in the manifest and then use the API to change your webhook subscriptons after your app is released to the App Center.

However, if you use the API to add a webhook to an app, and that new webhook requires a scope not previously configured in your manifest, then you'll need to update your manifest and your users will need to reconnect the app to accept this new permission.

​When a customer installs a new version of your app, any webhooks previously configured in the manifest will be deleted and replaced by the webhooks configured for the new version. Webhook subscriptions created using the API are copied into the newly installed version.

Receive Webhooks

When you subscribe to an event, you’ll receive a POST request at the URL you specified. To acknowledge that you received the webhook without error, your server should return a 200 HTTP status code, otherwise we will consider it not received (we will attempt 12 retries over a space of 48 hours before failing).

All webhooks contain the following payload:

client_id: your client ID found on your Developer Admin Portal page

client_version: the app’s version

event: the event name

timestamp: Unix epoc time

data : additional data, based on the event (refer to the docs to understand exactly what data will be returned)

hmac: the client_id, client_version, event, timestamp, and data, process through HMAC-SHA256 using the app's secret key.

​Fields will be in the same order as the list above. For example, for the site.publish webhook, you might have this in the hash:

site.publish Payload

You might decode and verify like this:

Decode and Verify the Hash

You can use the data provided in the webhook to fetch additional data from a relevant api. For example, say you want to be notified when an order is paid and then get additional info about the transaction. You would subscribe to the store.order.pay webhook.