Webhooks

Webhooks are a way to get notified when an event happens on your blog.

Note: Currently, only cache events are supported. They can be used for self-hosting your blog in a subdirectory. Other events will be added soon.

Event Dispatched
blog.updated Any setting of the blog is updated
   
post.created A new post is created
post.updated A post is updated
post.deleted A post is deleted
post.variant.created A post variant is created
post.variant.updated A post variant is updated
post.variant.deleted A variant is deleted
post.tags.changed Tags assigned to a post are changed
post.authors.changed Authors assigned to a post are changed
   
page.created A new page is created
page.updated A page is updated
page.deleted A page is deleted
page.variant.created A page variant is created
page.variant.updated A page variant is updated
page.variant.deleted A variant is deleted
   
tag.{events} (all page events are available for tags, except .tags.changed and .authors.changed)
user.{events} (all tag events are available for users)
   
navigation.changed Blog navigation changed
routes.changed Blog routes changed
languages.changed Blog languages changed
   
media.created A media item is added
media.deleted A media item is deleted
   
cache.single When cache of a single path should be cleared (styles.css, assets, media, etc.)
cache.templates When cache of all template-generated paths should be cleared (index, posts, feeds, etc.).
cache.all When all cache should be cleared

POST Request Body

When a subscribed event happens, we call the URL you provided, via the HTTP POST method. The request will have a JSON body like this. Contents of the data object varies depending on the event type.

{
    "subdomain": "my-subdomain",
    "timestamp": 1645208678,
    "event": "cache.single",
    "data": {

    }
}

cache.single will have the path that should be cleared from cache. cache.templates and cache.all events do not contain any data.

{
    "data": {
        "path": "/media/image.png"
    }
}

Security

In the console, you can find a key for each Webhook you create. This key is sent in each response. You can use it to verify the webhook using a simple string comparison. Something like:

if (request.post.key !== env.HB_WEBHOOK_KEY) {
    return "Unauthorized";
}

Keep this key secure.

Response & Retries

We expect a 200 HTTP Response Code from your server to mark the webhook as success. If we get any other response code or fail to reach your servers, we will retry to send the webhook for 3 more times after

If all fail, we will mark that webhook as failed and will no longer send it automatically. However, you can manually trigger it from the console later.