Connecting Ghost CMS to External Services: A Practical Guide to Custom Integrations with Webhooks and the Admin API

Goal: Automate Content Workflows with Ghost Custom Integrations

When you need to push Ghost posts to an external marketing platform, sync member data to a CRM, or trigger a CI pipeline on post publication, Ghost’s Custom Integration feature gives you a single, secure API key and optional webhook endpoint. This guide shows how to create that integration, validate the key, configure a webhook, and confirm that events reach your third‑party service.

Prerequisites

• Ghost CMS instance (self‑hosted or Ghost Pro) with administrative access.
• Network connectivity to the external service you plan to integrate with.
• Credentials for the external service (e.g., API key, webhook URL).
• Tool for sending HTTP requests (cURL, Postman, or similar).

Step 1: Create the Custom Integration in the Admin Dashboard

1. Log in to https://YOUR_GHOST_ADMIN_URL/ghost as an administrator.
2. Navigate to Settings > Integrations > Custom Integration.
3. Click Add Custom Integration.
   • Give the integration a descriptive name (e.g., "Marketing Automation").
   • Optionally, provide a description and an icon URL.
4. Click Save. Ghost will generate:
   • A unique Admin API key (a long string of random characters).
   • An Admin API base URL (e.g., https://YOUR_GHOST_ADMIN_URL/ghost/api/v3/admin/).
5. Immediately copy the key to a secure location. The key is shown only once.

Security Considerations

The Admin API key grants full read/write access to the site’s content and configuration. Treat it like a root password:

• Store it in a secrets manager or environment variable.
• Never commit it to version control.
• Revoke and regenerate if you suspect compromise.

Step 2: Test the Admin API Key

Verify that the key works by fetching a list of posts. Run the following cURL command from a terminal that can reach your Ghost instance:

curl \
  -H "Authorization: GhostApi " \
  https://YOUR_GHOST_ADMIN_URL/ghost/api/v3/admin/posts/

Expected result: a JSON array of post objects. If you receive a 401 Unauthorized, double‑check the key and that you are using the correct Admin API URL.

Step 3: Configure a Webhook Endpoint

Webhooks allow Ghost to push real‑time notifications to a URL. For this example, we’ll use RequestBin to capture the payload.

1. Open a new RequestBin instance (or any public echo service) and note the URL (e.g., https://webhook.requestbin.io/xxxx-xxxx-xxxx).
2. Return to Ghost Admin, Settings > Integrations > Custom Integration, and edit the integration you created.
3. Under Webhook, enter the RequestBin URL.
4. Optionally, set a Secret string. Ghost will sign the payload with HMAC SHA256; your receiver can verify the signature using this secret.
5. Choose the Events you want to track. Common selections:
   • Post published
   • Member signed up
   • Member updated
6. Click Save.

Webhook Payload Structure

When a selected event occurs, Ghost sends a JSON payload that looks like:

{
  "event": "post.published",
  "data": {
    "id": "abcd1234",
    "title": "Hello World",
    "slug": "hello-world",
    "created_at": "2026-10-16T23:00:00.000Z",
    "updated_at": "2026-10-16T23:00:00.000Z"
  },
  "secret": ""
}

Step 4: Trigger an Event and Verify Delivery

Publish a new post from the Ghost editor or via the Admin API to fire the webhook. Then check RequestBin:

• Navigate to the RequestBin dashboard.
• Open the most recent request. You should see the JSON payload above.
• Verify that the secret field matches the HMAC signature if you set a secret.

Common Troubleshooting

• No payload received – Ensure the webhook URL is reachable from the Ghost server (no firewall blocking outbound HTTPS).
• Signature mismatch – The secret on Ghost and the receiver must match exactly; case‑sensitive.
• Rate limits – Ghost Pro imposes a 10 requests/second limit per API key. High‑traffic sites may need a dedicated integration per service.

Step 5: Clean Up (Optional)

If you no longer need the integration, revoke the key and remove the webhook:

1. In the Ghost Admin, edit the integration and click Revoke API Key.
2. Delete the webhook entry or remove the integration entirely.

Recovery Options

• If the integration key is lost, you can generate a new key by editing the integration and clicking Regenerate API Key.
• To restore webhook functionality after deletion, re‑create the webhook with the same URL and secret.

Practical Use Cases

• Marketing Automation – Push new posts to a newsletter service whenever a post is published.
• Analytics & Reporting – Send member signup events to a data warehouse for cohort analysis.
• CI/CD Triggers – Trigger a build pipeline on a Git repository when a post is updated.

Limitations & Considerations

• Admin API keys are powerful; misuse can alter site settings or delete content.
• Webhook delivery is fire‑and‑forget; Ghost does not retry failed deliveries. Design your receiver to be idempotent.
• Self‑hosted Ghost may not enforce strict rate limits; monitor your integration endpoint for overload.
• For highly secure environments, consider rotating keys regularly and using IP whitelisting on your receiver.

How to Verify the Integration Works in Production

1. Deploy a small test script on your production server that listens for the webhook URL and logs the payload.
2. Publish a test post and watch the logs for the event.
3. Use the Admin API to fetch the post by ID and confirm the data matches the webhook payload.
4. Check for any 5xx responses from Ghost; if present, investigate network or firewall issues.

Conclusion

Ghost’s Custom Integration feature turns your CMS into a powerful event source. By generating a secure Admin API key and setting up a webhook, you can automate workflows, sync data, and extend Ghost’s capabilities without custom code on the Ghost side. Always treat the key with care, verify payload integrity, and monitor your external endpoints for reliability.