Skip to main content

Publishing via webhooks

Webhooks let you send articles to any endpoint you control when you publish them. Combined with automation platforms like Zapier, Make.com, or n8n, you can publish to any CMS or trigger any workflow, without writing code.

A webhook is sent only when you publish an article to it. Writing an article, or publishing it to a CMS, doesn't trigger a webhook.

Setting up a webhook​

Open Project settings (the gear icon next to the project name at the top of the page), go to the Integrations tab, and click the Webhook tile under Connect a CMS.

Only workspace owners and admins can add, edit or remove webhooks.

Enter a Name and the URL of your webhook endpoint. The URL is provided by your automation platform. Create a webhook trigger in Zapier, Make.com, or n8n and paste the URL here.

Image links in the payload work for 24 hours, so make sure your destination saves its own copy of any images.

Advanced settings​

Expand Advanced settings to configure the HTTP method and authentication.

HTTP method​

POST, PUT, or PATCH. Most platforms use POST.

Authentication​

Secures the request so only Machined can call your endpoint:

  • None: no authentication
  • Bearer token: adds an Authorization: Bearer <token> header
  • Basic auth: enter your credentials as username:password; Machined encodes them for you
  • API key (header): sends a key in a request header. The Header name defaults to X-API-Key.
  • API key (query): adds a key to the URL as a query parameter. The Query parameter defaults to api_key.

Click Add webhook to save.

Signing secret​

When you create a webhook, Machined generates a signing secret. Copy it straight away, because it won't be shown again.

Every request includes two headers your endpoint can use to check that the request genuinely came from Machined:

  • X-Machined-Timestamp: the time the request was sent, in Unix seconds
  • X-Machined-Signature: sha256= followed by a hex HMAC-SHA256 signature

To verify a request, join the timestamp, a full stop and the raw request body ({timestamp}.{body}), compute an HMAC-SHA256 of that string using your signing secret, and compare it with the signature in the header.

Regenerating the secret​

If you lose the secret or think it's been exposed, edit the webhook and click Regenerate next to the signing secret. The old secret stops working immediately, so update your endpoint with the new one straight away.

Managing webhooks​

Your webhooks are listed in the Webhooks section of the Integrations tab.

Each webhook has the following controls:

  • Toggle: enable or disable the webhook. Disabled webhooks won't be sent.
  • Test webhook: sends a sample payload (titled "Test Article Title") so you can check your endpoint is working. The response status is shown next to the webhook's name.
  • Edit webhook: update the name, URL, HTTP method, authentication, or regenerate the signing secret.
  • Move to another project: move the webhook to a different project.
  • Delete webhook: permanently remove the webhook.

Sending articles to a webhook​

Webhooks appear alongside your CMS connections in the publish dialog:

  1. Open a written article and click Publish (or choose Publish article from its menu in a cluster)
  2. Choose your webhook as the destination
  3. Confirm on the Send to screen

Once sent, the article is marked Posted. To send several articles at once, select them in a cluster and click Publish (n). This works even if a webhook is your project's only destination.

To send an updated version of an article, use Republish, which sends it to the same webhook. Unpublish only resets the status in Machined; nothing is sent to your webhook. See Republishing and unpublishing.

Webhooks aren't limited by the one-CMS-per-article rule. Publishing to a webhook replaces an article's previous CMS publish status, and vice versa.

Handling duplicates​

In rare cases, such as a retry or publishing the same article from two browser tabs, your endpoint can receive the same article more than once. Use article_id to spot and ignore duplicates.

Webhook payload​

Each request contains the following fields:

{
  "cluster_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "cluster_topic": "how to grow tomatoes",
  "cluster_audience": "home gardeners",
  "article_id": "3f2b8c1e-5a4d-4e6f-9b7a-1c2d3e4f5a6b",
  "article_slug": "best-tomato-varieties",
  "article_title": "The Best Tomato Varieties for Home Gardeners",
  "article_description": "A guide to choosing the right tomato varieties for your garden.",
  "article_keyword": "best tomato varieties",
  "article_content_markdown": "## Introduction\n...",
  "article_content_html": "<h2>Introduction</h2><p>...</p>",
  "article_featured_image": "https://example.com/featured-image.jpg",
  "article_featured_image_alt_text": "best tomato varieties",
  "article_featured_image_caption": "Photo by photographer on Pexels"
}

For a single article that isn't part of a cluster, cluster_id, cluster_topic and cluster_audience are null.

Last updated on