Skip to content

Webhooks

One webhook per platform per post. When something fails you get the reason in plain words and whether retrying can help.

  • A result per platform, not one blended status
  • Plain-English failure reasons
  • A retryable flag on every failure
  • The key and run ID included
webhook.tsnode
1// Your endpoint receives one event per platform.2app.post("/postkey/webhook", (req, res) => {3  const event = req.body;4  if (event.type === "post.failed" && event.retryable) {5    retryLater(event.postId);6  }7  res.sendStatus(200);8});

post.failed · instagram

What comes back

{
  "type": "post.failed",
  "postId": "post_8f21c",
  "account": "acc_ig_123",
  "platform": "instagram",
  "status": "failed",
  "reason": "account_not_professional",
  "message": "This is a personal account. Instagram only publishes to Business or Creator accounts.",
  "retryable": false
}

How it works

  • Per platform

    A post to four networks sends four events. You know exactly which one failed.

  • Readable reasons

    Platform error codes turned into a sentence you can show a customer.

  • Retry or don't

    Every failure says whether a retry can help, so you don't hammer a post that will never go out.

Works with your stack

  • Your code

    Node and Python SDKs with the same calls, or plain REST from anything that speaks HTTP.

    • Node
    • Python
    • {}REST
    Read the docs
  • No-code tools

    Call the REST API from an HTTP step in n8n, Make or Zapier. Give each workflow its own key.

    • n8n
    • Make
    • Zapier
    Postkey with n8n
  • AI agents & MCP

    The MCP server lets Claude, Cursor and other agent tools post through their own key, with caps they can't change.

    • MCP server
    About the MCP server

Questions

Something not here? Email hello@postkey.dev.

Which events are sent?

When a post goes out, fails, finishes processing, or a scheduled post is published, per platform.

Do I have to use webhooks?

No. Immediate results come back in the API response. Webhooks matter most for video and scheduled posts, which finish later.

Can I verify a webhook came from Postkey?

Yes. Each request is signed so you can check it before trusting it.

Give everyone who posts their own key.

Get a key, connect an account, send your first request.