Skip to main content

​
Overview

Webhooks allows Ghost to send POST requests to user-configured URLs in order to send them a notification about it. The request body is a JSON object containing data about the triggered event, and the end result could be something as simple as a Slack notification or as complex as a total redeployment of a site.

​
Setting up a webhook

Configuring webhooks can be done through the Ghost Admin user interface under Settings > Advanced > Integrations > Add custom integration. The only required fields to setup a new webhook are a trigger event and target URL to notify. This target URL is your application URL, the endpoint where the POST request will be sent. Of course, this URL must be reachable from the Internet. If the server responds with 2xx HTTP response, the delivery is considered successful. Anything else is considered a failure of some kind, and anything returned in the body of the response will be discarded.

​
Available events

Currently Ghost has support for below events on which webhook can be setup:
EventDescription
site.changedTriggered whenever any content changes in your site data or settings
post.addedTriggered whenever a post is added to Ghost
post.deletedTriggered whenever a post is deleted from Ghost
post.editedTriggered whenever a post is edited in Ghost
post.publishedTriggered whenever a post is published to Ghost
post.published.editedTriggered whenever a published post is edited in Ghost
post.unpublishedTriggered whenever a post is unpublished from Ghost
post.scheduledTriggered whenever a post is scheduled to be published in Ghost
post.unscheduledTriggered whenever a post is unscheduled from publishing in Ghost
post.rescheduledTriggered whenever a post is rescheduled to publish in Ghost
page.addedTriggered whenever a page is added to Ghost
page.deletedTriggered whenever a page is deleted from Ghost
page.editedTriggered whenever a page is edited in Ghost
page.publishedTriggered whenever a page is published to Ghost
page.published.editedTriggered whenever a published page is edited in Ghost
page.unpublishedTriggered whenever a page is unpublished from Ghost
page.scheduledTriggered whenever a page is scheduled to be published in Ghost
page.unscheduledTriggered whenever a page is unscheduled from publishing in Ghost
page.rescheduledTriggered whenever a page is rescheduled to publish in Ghost
tag.addedTriggered whenever a tag is added to Ghost
tag.editedTriggered whenever a tag is edited in Ghost
tag.deletedTriggered whenever a tag is deleted from Ghost
post.tag.attachedTriggered whenever a tag is attached to a post in Ghost
post.tag.detachedTriggered whenever a tag is detached from a post in Ghost
page.tag.attachedTriggered whenever a tag is attached to a page in Ghost
page.tag.detachedTriggered whenever a tag is detached from a page in Ghost
member.addedTriggered whenever a member is added to Ghost
member.editedTriggered whenever a member is edited in Ghost
member.deletedTriggered whenever a member is deleted from Ghost

​
Stripe webhooks

Webhooks allow Ghost to communicate with Stripe. In order to use Stripe with a local version of Ghost you’ll need to do some additional setup to allow webhook events happen between Stripe and Ghost. First, follow the instructions on how to install and log into the Stripe CLI tool in the Stripe documentation. Then, before starting a local instance of Ghost, run the following command in your CLI. Note that the localhost port number should match the one used in your local Ghost install: 
stripe listen --forward-to http://localhost:2368/members/webhooks/stripe/
After running this the CLI will return a secret prefixed with whsec_. This secret needs to be given to Ghost on start up. In a new CLI window run the following: 
WEBHOOK_SECRET=whsec_1234567890abcdefg ghost start
After following these steps, Ghost will run locally with a webhook connection to your Stripe account. To test that it’s working, sign up for a paid membership on the local site. Now that the local install of Ghost is running and communicating with Stripe, you can develop and test themes for a custom membership experience, build signup and signin forms, or expose member data.