Webhooks

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

  • A blog can have up to 5 webhooks
  • Each webhook can subscribe to one or more events
Currently, only cache events are enabled. They can be used for subdirectory hosting. The other events will be enabled in February 2024.
Event
Dispatched
Data
blog.updated
Any setting of the blog is updated
Post
post.created
A new post is created
post.updated
A post is updated
post.deleted
A post is deleted
post.tags.changed
Tags assigned to a post are changed
post.authors.changed
Authors assigned to a post are changed
Pages
page.created
A new page is created
page.updated
A page is updated
page.deleted
A page is deleted
page.tags.changed
Tags assigned to a page are changed
page.authors.changed
Authors assigned to a page are changed
Tags
tag.created
A new tag is created
tag.updated
A tag is updated
tag.deleted
A tag is deleted
Users
user.created
A new user is created
user.updated
A user is updated
user.deleted
A user is deleted
Media
media.created
A media item is added
media.deleted
A media item is deleted
Other
navigation.changed
routes.changed
Blog routes changed
languages.changed
Cache Clearing
cache.single
When cache of a single path should be cleared (styles.css, assets, media, etc.)
{path: string}
cache.templates
When cache of all template-generated paths should be cleared (index, posts, feeds, etc.)
Empty object
cache.all
When all cache should be cleared
Empty object

Webhook Request

When an event happens, a POST request is sent to the webhook URL. The request body is a JSON object with the following properties. The content property is the event data. See the above table for the event data structure.

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

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.

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

Soon we will be moving to a signature-based method for verification.

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

  • 1 minute
  • 5 minutes
  • 30 minutes

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.