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
Event
Dispatched
Data
blog.updated
Any setting of the blog is updated
{ blog: Blog }
Post
post.created
A new post is created
{ post: Post }
post.updated
A post is updated
{ post: Post }
post.deleted
A post is deleted
{ post: Post }
Tags
tag.created
A new tag is created
{ tag: Tag }
tag.updated
A tag is updated
{ tag: Tag }
tag.deleted
A tag is deleted
{ tag: Tag }
Users
user.created
A new user is created
{ user: User }
user.updated
A user is updated
{ user: User }
user.deleted
A user is deleted
{ user: User }
Media
media.created
A media item is added
{ media: Media }
media.deleted
A media item is deleted
{ media: Media }
Other
navigation.changed
{ navigation: Navigation[] }
routes.changed
Blog routes changed
{ routes: Route[] }
languages.changed
{ languages: Language[] }
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.