Connect Webhook to PilotDeck

What connecting a webhook does#

A CMS connection is the last hop of the PilotDeck pipeline: once you approve a draft, PilotDeck delivers it for you. With Webhook, the destination is a URL you own. PilotDeck sends the article as a signed JSON POST, and your side decides how to store and render it. The example below uses a PilotDeck site named pilotdeck-testwebsite.

Before you start#

Overview#

1. 1Build or choose an HTTPS endpoint that accepts a JSON POSTYou
2. 2Open Settings > Integrations in PilotDeck and pick WebhookYou
3. 3Enter the Webhook URL and choose a publish modeYou
4. 4Connect. PilotDeck sends a signed ping and creates the signing secretPilotDeck
5. 5Save the signing secret in your receiverYou
6. 6Send a test draft and check your endpoint received itVerify

What PilotDeck sends#

Each article is one POST with Content-Type: application/json and the user agent Pilotdeck-Connector/1.0. The body is a JSON envelope. Values below are placeholders. Optional author fields are left out when empty.

{
  "event": "post.publish",
  "deliveryId": "<unique-delivery-id>",
  "post": {
    "id": "<post-id>",
    "title": "Example article title",
    "slug": "example-article-title",
    "html": "<h2>Example heading</h2><p>Article body as HTML.</p>",
    "metaTitle": "Example article title | Example",
    "metaDescription": "A short description for search results.",
    "tags": [],
    "categories": [],
    "faq": [
      { "question": "Example question?", "answer": "Example answer." }
    ],
    "conclusion": "",
    "author": {
      "name": "Example Author",
      "title": "Example role",
      "bio": "Short bio.",
      "url": "https://example.com/authors/example",
      "image": "https://example.com/authors/example.png",
      "slug": "example"
    },
    "featuredImage": "https://example.com/images/hero.png",
    "ogImage": "https://example.com/images/hero.png",
    "images": [],
    "status": "draft",
    "publishedAt": null,
    "updatedAt": "2026-01-01T00:00:00.000Z",
    "canonical": null
  },
  "jsonLd": [
    { "@context": "https://schema.org", "@type": "FAQPage" },
    { "@context": "https://schema.org", "@type": "BlogPosting" }
  ],
  "sentAt": "2026-01-01T00:00:00.000Z"
}

The jsonLd entries are shortened above. In a real delivery they are complete schema.org objects: an FAQPage when the article has FAQ entries, and a BlogPosting that includes the author when there is one.

Request headers and signature#

To verify a request, compute the HMAC-SHA256 of the exact raw body using your signing secret, prefix it with sha256=, and compare it to the header with a constant-time comparison. Verify the raw bytes before parsing the JSON, because re-serialising the body can change it.

const crypto = require("crypto");

function isValidSignature(rawBody, header, secret) {
  const expected =
    "sha256=" +
    crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(header || "");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

// rawBody: the unparsed request body
// header: the X-Pilotdeck-Signature value
// secret: process.env.PILOTDECK_SIGNING_SECRET (<your-signing-secret>)

The ping event#

Test connection and Connect both send a ping. It has the same envelope as an article, with event set to ping, post set to null and jsonLd as an empty list. It is signed like any other request.

PilotDeck creates the signing secret for each attempt, and you only see the final one after Connect succeeds. So the ping signature cannot be checked against a secret you already hold. Answer ping with a 2xx status without rejecting it on signature, then enforce signatures on post.publish once you have saved the secret.

Timeouts and failures#

Each delivery is a single attempt. The webhook adapter does not retry on its own, so make your endpoint fast, acknowledge quickly, and do heavy work after answering. Because a delivery can be sent more than once if a deploy is run again, treat deliveryId and post.slug as keys and make your handler idempotent.

Publish mode#

The webhook connector does not read this setting. It cannot create a draft or schedule anything on your side, because it only delivers JSON. A delivery looks the same in either mode, and what happens next is decided by your receiver. If you want a review step, hold the article in your own system until someone approves it.

Disconnecting#

On the connected card click Disconnect and confirm. Approved content stops being delivered right away. To reconnect, repeat steps 2 to 4. You receive a new signing secret, so update your receiver with it. Remove the old secret from your receiver when you disconnect.

Troubleshooting#