Integrations and webhooks

Overview

Ghost can notify your team in real time whenever something happens in your workspace. You can use native integrations, signed webhooks, or both:

• Slack and Microsoft Teams use OAuth. You sign in once, choose where messages go, and Ghost posts notifications through each platform's API (Slack Block Kit in Slack; Adaptive Cards in Teams).
• Webhooks send signed JSON payloads to any HTTPS endpoint you control, so you can pipe events into ticketing systems, SIEM tools, or your own automation.

Both options live under Settings > Integrations. You need a Team plan and an admin or owner role to set them up.

Connecting Slack

The Slack integration uses OAuth, so there is nothing to configure on Slack's side first. Click the Slack card on the Integrations page and then Connect Slack. You will be redirected to Slack where you pick a workspace and channel, then approve the connection.

Once connected, Ghost posts to that channel automatically. The integration card shows the channel name and the latest delivery status. From the detail page you can:

• Test the connection by sending a sample notification.
• Pause or resume delivery without removing the connection.
• Disconnect entirely if you no longer need it.

Slack messages use Block Kit formatting with a header, body, a button linking back to Ghost, and a context line showing your organisation name.

Connecting Microsoft Teams

The Teams integration uses Microsoft identity (Azure AD) and the Microsoft Graph API, so you connect with the account that can access the team and channel you want.

Open the Microsoft Teams card on Settings > Integrations and choose Connect Teams. You are redirected to Microsoft to sign in and consent to the requested permissions (list teams and channels, send channel messages).

After OAuth completes, open the Teams integration page in Ghost. If no channel is selected yet, use Select channel and pick the team and channel that should receive notifications. Delivery does not start until a channel is set.

From the detail page you can Test the connection, pause or resume delivery, change channel, tune which event categories and event types are sent (same pattern as Slack), and Disconnect when you no longer need the connection.

Messages appear in Teams as Adaptive Cards: title, body, and a link back to Ghost in the channel you selected.

Webhooks

Webhooks are for endpoints you own. Every webhook you create in Ghost gets its own HMAC-SHA256 signing secret, which Ghost uses to sign each outgoing request. This lets your server verify that payloads genuinely came from Ghost and have not been tampered with.

To receive webhooks your endpoint needs to:

• Accept POST requests with a Content-Type: application/json body over HTTPS.
• Respond with a 2xx status within five seconds. Ghost retries once after a short delay if it receives a 429.

Webhook signing

When Ghost delivers a webhook it includes two extra headers:

• X-Ghost-Signature contains the HMAC-SHA256 hex digest of the raw request body, keyed with your webhook's signing secret.
• X-Ghost-Timestamp is the Unix epoch (in seconds) when the request was created. Compare this to the current time to guard against replay attacks.

To verify a delivery, recompute the HMAC of the raw body using your signing secret and check that it matches the X-Ghost-Signature header. Most languages have a built-in HMAC library that makes this straightforward.

Your signing secret is shown once when the webhook is created. Copy it and store it somewhere safe. If you lose it, you can rotate it from the webhook card, which immediately generates a new secret and invalidates the old one.

Creating a webhook

1. Open Settings > Integrations and click Add webhook in the Webhooks section.
2. Give the webhook a label so your team can identify it later.
3. Paste the endpoint URL of your receiving service.
4. Select one or more event categories(for example Privacy Request Cases & Tasks, Article 30 Register, Team, Redaction, Breach register, DPIA, Third Parties, Retention, Consent, Training, or Policies). Leaving all unchecked subscribes to everything.
5. When Breach register is included, you can optionally enable Limit breach events only and choose specific breach notification types instead of all breach-related events.
6. Save. Ghost creates the webhook, generates a signing secret, and displays it in a banner at the top of the card. Copy the secret before navigating away.

Managing webhooks

Each webhook card shows its label, a truncated URL, event categories, status badge, and the last delivery result. You can:

• Test to send a sample payload and confirm the endpoint picks it up.
• Edit to change the label, URL, or event categories.
• Enable or disable to pause notifications without deleting the webhook.
• Rotate secret to generate a new signing secret. The old one stops working immediately, so update your server before rotating.
• Delete to permanently remove the webhook.

Event categories

Categories group related events so you can subscribe to exactly what matters for each integration or webhook:

• Privacy Request Cases & Tasks — case lifecycle, tasks, deadlines, intakes, response packs, comments, and identity verification follow-ups.
• Article 30 Register — processing activities, gap alerts, and review due reminders.
• Team — invitations, joins, removals, roles, and matter access.
• Redaction — redaction review comments and related events.
• Breach register — breach logging and DPC / authority deadline reminders.
• DPIA, Third Parties, Retention, Consent, Training, and Policies — compliance-area notifications for those registers and workflows.

On the Slack and Teams detail pages you can optionally narrow further to specific event types within the categories you selected. On webhooks, when Breach register is included, you can limit to selected breach event types using Limit breach events only.

Payload shapes

Single event

Each notification is a flat JSON object. The type field is Ghost's internal event identifier (a stable snake_case string such as case_assigned, breach_logged, or member_joined).

• type (string, the event id)
• title (string)
• body (string, plain text, may include newlines)
• href (string, absolute URL to the relevant screen in Ghost)
• orgName (string, workspace name)
• metadata (object, optional, event-specific fields)
• timestamp (string, ISO 8601, UTC)

Digest

Batched digest deliveries use type: "digest" and include an items array instead of a single body.

• type ("digest")
• subject (string, summary line)
• items (array of { type, title, body, href })
• href (string, link for the batch)
• orgName (string)
• timestamp (string, ISO 8601)

Test payload

Clicking Test sends a synthetic event with type: "test", a fixed title and body, and a link back to Settings > Integrations. The shape is the same as a real single event.

Tips

• Use the Slack or Teams integrations for day-to-day channel alerts, and reserve webhooks for programmatic consumers like SIEMs, ticketing APIs, or automation platforms.
• Create separate webhooks for different audiences. For example, one for the legal team subscribed to privacy requests and Compliance, and another for IT subscribed to Redaction and Team.
• Always test a new webhook or integration before relying on it. The test payload confirms the URL, authentication, and formatting all work.
• Check the delivery health indicator on each card periodically. If deliveries start failing (for example because a Slack channel was archived, a Teams channel was removed, or an endpoint went down), Ghost surfaces the problem on the card.
• Keep your signing secret safe. If you suspect it has been exposed, rotate it from the webhook card and update your server with the new secret straight away.

For background on settings and team configuration, read Settings and team management.