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 }
post.variant.published
A post variant is published
{ post: Post, variant: PostVariant, }
post.variant.unpublished
A post variant is unpublished
{ post: Post, variant: PostVariant, }
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 data property is the event data. See the above table for the event data structure.

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

Security

Each webhook request includes an X-Signature header containing an HMAC-SHA256 signature of the request body, signed with your webhook’s secret key. You can find the secret in the Console under your webhook settings.

To verify the signature:

  • Hash the request body using HMAC-SHA256 with your webhook’s secret key.
  • Compare the resulting hash with the value of the X-Signature header.
const signature = request.headers['x-signature'];
const expected = crypto
	.createHmac('sha256', env.HB_WEBHOOK_SECRET)
	.update(JSON.stringify(request.body))
	.digest('hex');

if (signature !== expected) {
	return 'Unauthorized';
}

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.

Hyvor Blogs Logo