Webhooks API
You use webhooks to notify your app of events in a Weebly site. For example, your app might need to be notified when a site is published, so you would use the site.publish webhook to get notified of that event.
You subscribe your app to webhooks in the manifest, providing a callback URL to receive the event payload. However, you can use the Webhook API to to change webhook subscriptions once your app is released to the Weebly App Center.
Your callback_url can be used for multiple events, and in fact, best practice is to have a single webhook with all the events targeting the same callback_url. The API allows for unique cases, however.
Instead of the Webhook API requiring specific scopes, the scope depends on the webhook being subscribed to. Review the webhook documentation for needed scopes.
Use the Webhook API to retrieve, create, update, and delete webhooks for a given app on a given site.
You subscribe your app to webhooks in the manifest, providing a callback URL to receive the event payload. However, you can use the Webhook API to to change webhook subscriptions once your app is released to the Weebly App Center.
Your callback_url can be used for multiple events, and in fact, best practice is to have a single webhook with all the events targeting the same callback_url. The API allows for unique cases, however.
Instead of the Webhook API requiring specific scopes, the scope depends on the webhook being subscribed to. Review the webhook documentation for needed scopes.
Use the Webhook API to retrieve, create, update, and delete webhooks for a given app on a given site.
Note: Best practice is to set default webhooks in the manifest and then use the API to change your webhook subscriptions 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.
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.
Note: To authenticate with the Weebly API, you need to use OAuth. This will allow you to access resources based on a particular user and site.
In this topic:
Fields
The following table shows all fields that exist for this API, those that are returned when you retrieve a list, those that are required for POST, and those that are changeable using PATCH. All fields are returned when you retrieve a single item.
Name |
Description |
Type |
List |
Req'd |
Change- able |
user_id |
Unique ID of the user authenticated during the OAuth process |
string |
X |
||
site_id |
ID of a Weebly site, unique to the currently authenticated user |
string |
X |
||
webhook_id |
Unique ID (to this app's installation on the site) for the webhook. |
string |
X |
||
callback_url |
The URL that the event is sent to. It must use the HTTPS protocol. Note: You will not be able to upload an app to the App Center if it uses HTTP. |
string |
X |
X |
X |
event |
Array of events that this webhook is subscribed to. |
string (if single event) or an array |
X |
X |
X |
headers |
Array of name/value pair objects returned with each event. For example, the site.publish webhook returns the following when the site is published:
|
array |
X |
Note: Any fields returned that are not documented are currently unsupported and can be safely ignored.
Retrieve a List of an App's Webhooks for a Site
Endpoint URL
Returns all the app's webhooks created for this site. The app ID is determined by the OAuth token.
Query Parameters
Parameter |
Description |
Type |
page |
Which page of results to return. Start is 1. Note: Only the first 25 results are returned by default. If the result set is expected to be over 25, you must implement pagination. |
integer |
limit |
Number of results per page to return. Default is 25. Max is 200. |
integer |
query |
Use to retrieve only snippets that have a full-text match with the query string. |
string |
filterby |
Field name to set a filter on. |
string |
filterfor |
Value to search the filterby field for. |
string |
sortby |
Field to sort on. You can sort on:
|
string |
sortdir |
Sort direction. Valid values are:
|
string |
Request
Example returning all webhooks:
Example of filtered request
Response
Example response
Retrieve Details for an App's Webhook
Enpoint URL
Returns the details for a given webhook.
Request
Example request
Response
See Fields table. All fields for the webhook are returned.
Example response
Create an App's Webhook for a Site
Endpoint URL
Creates a new webhook for the app on the site.
POST body:
These fields can be created.
Name |
Description |
Type |
Notes |
event |
Array of events that this webhook is subscribed to. |
array |
Required |
callback_url |
The URL that the event is sent to. It must use the HTTPS protocol. Note: You will not be able to upload an app to the App Center if it uses HTTP. |
string |
Required |
headers |
Array of name/value pair objects returned with each event. For example, the site.publish webhook returns the following when the site is published:
|
Request
Example request
Response
Example response
Update an App's Webhook for a Site
Endpoint URL
Updates the given webhook.
Updateable Fields
These fields can be updated.
Name |
Description |
Type |
event |
Array of events that this webhook is subscribed to. |
array |
callback_url |
The URL that the event is sent to. It must use the HTTPS protocol. Note: You will not be able to upload an app to the App Center if it uses HTTP. |
string |
Request
Example request
Response
Example response
Delete an App's Webhook for a Site
Endpoint URL
Deletes the given webhook.
Request
Example request
Response
There is no response to a delete request.
Related Topics:
Use the REST API
Use the REST API