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.

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 Required Changeable
user_id The unique ID of the authenticated user 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. string X X X
event Array of events that this webhook is subscribed to. Array of strings 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:
  • user_id
  • site_id
  • domain
array X

GET
Retrieve a List of Webhooks

GET /v1/webhooks

Returns all webhooks for the given site. The app_id is determined by the OAuth token.

Query Parameters

Returned values are paginated. You can further filter results using these parameters:

Parameter Description Type
page Which page of results to return. Start is 1. integer
limit Number of results per page to return. Default is 25.
Max is 200.
integer
query Use to retrieve only pages 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.
You can use the following URL encoded operators with your filterfor parameter:
  • ​<: use %3C
  • >: use %3E
  • <=: use %3C%3D
  • >=: use %3E%3D
string
sortby Field name to sort by. You can sort by:
  • webhook_id
  • callback_url
  • event
string
sortdir Sort direction. Valid values are:
  • asc
  • desc
string

Example CURL request returning all webhooks:

curl --request GET \
--url https://api.weebly.com/v1/webhooks \
--header 'accept: application/vnd.weebly.v1+json' \
--header 'content-type: application/json' \
--header 'x-weebly-access-token: [YOUR_TOKEN]"

Example filtered request:

curl --request GET \
--url https://api.weebly.com/v1/webhooks?sortby=event&sortdir=asc \
--header 'accept: application/vnd.weebly.v1+json' \
--header 'content-type: application/json' \
--header 'x-weebly-access-token: [YOUR_TOKEN]"

Example response:

[
  {
    "user_id": "123456",
    "webhook_id": "8",
    "site_id": "987654321",
    "callback_url": "https://myapp.com/weebly/webhook/",
    "event": "store.order.create",
    "headers": null
  },
  {
    "user_id": "123456",
    "webhook_id": "9",
    "site_id": "987654321",
    "callback_url": "https://myapp.com/weebly/webhook/",
    "event": "store.order.pay",
    "headers": null
  },
  {
    "user_id": "123456",
    "webhook_id": "10",
    "site_id": "987654321",
    "callback_url": "https://myapp.com/weebly/webhook/",
    "event": "store.order.refund",
    "headers": null
  }
 ]

GET
Retrieve Details for a webhook

GET /v1/webhooks/{WEBHOOK_ID}/

Returns all fields for the given webhook.

Example CURL request:

curl --request GET \
--url https://api.weebly.com/v1/webhooks/9 \
--header 'accept: application/vnd.weebly.v1+json' \
--header 'content-type: application/json' \
--header 'x-weebly-access-token: [YOUR_TOKEN]"

Example response:

See Fields table. All fields for the webhook are returned.

{
  "user_id": "123456",
  "webhook_id": "9",
  "site_id": "987654321",
  "callback_url": "https://myapp.com/weebly/webhook/",
  "event": "store.order.pay",
  "headers": null
}

POST
Create a Webhook

POST /v1/webhook

Creates a webhook for the authorized app.

These fields can be created:

Name Description Type Notes
callback_url The URL that the event is sent to. It must use the HTTPS protocol. string Required
event Array of events that this webhook is subscribed to. Array of strings 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:
  • user_id
  • site_id
  • domain
array

Example CURL request:

curl --request POST \
--url https://api.weebly.com/v1/webhooks \
--header 'accept: application/vnd.weebly.v1+json' \
--header 'content-type: application/json' \
--header 'x-weebly-access-token: [YOUR_TOKEN]"
--data '{
            "event": "site.delete",
            "callback_url": "https://myapp.com/weebly/webhook/"
         }'

Example response:

{
  "user_id": "123456",
  "webhook_id": "15",
  "site_id": "987654321",
  "callback_url": "https://myapp.com/weebly/webhook/",
  "event": "site.delete",
  "headers": null
}

PATCH
Update a Webhook

PATCH /v1/webhooks/{WEBHOOK_ID}

Updates the given webhook.

These fields can be updated:

Name Description Type
callback_url The URL that the event is sent to. It must use the HTTPS protocol. string
event Array of events that this webhook is subscribed to. Array of strings

Example CURL request:

curl --request PATCH \
--url https://api.weebly.com/v1/webhooks/15 \
--header 'accept: application/vnd.weebly.v1+json' \
--header 'content-type: application/json' \
--header 'x-weebly-access-token: [YOUR_TOKEN]"
--data '{
            "callback_url":"https://myapp.com/weebly/webhooks2"
        }'

Example response:

See Fields table. All fields for the webhook are returned.</p>

{
  "user_id": "123456",
  "webhook_id": 15,
  "site_id": "987654321",
  "callback_url": "https://myapp.com/weebly/webhook2/",
  "event": "site.delete",
  "headers": null
}

DELETE
Delete a Webhook

DELETE /v1/webhooks/{WEBHOOK_ID}

Deletes the given webhook.

Example CURL request:

curl --request DELETE \
--url https://api.weebly.com/v1/webhooks/15 \
--header 'accept: application/vnd.weebly.v1+json' \
--header 'content-type: application/json' \
--header 'x-weebly-access-token: [YOUR_TOKEN]"

Response

There is no response to a delete request.


Help make these docs better!









Tags:
webhooks apis