Use Postkeg from your own code
Postkeg is built around its API: your own systems post and read results over a small web API (an assistant can use the same service): posts, channels, files, results and the inbox, plus webhooks that tell you when a post goes out.
Start in two minutes
- Sign in, open Connections, then API keys, and make a key. Tick only what your code needs. Copy it right away: it is shown once.
- Send it with every call as
Authorization: Bearer YOUR_API_KEY. - Check that it works:
curl https://api.postkeg.com/api/v1/me \
-H "Authorization: Bearer YOUR_API_KEY"
A key acts as the person who made it and never with more rights. If that person is later removed from the workspace, the key stops working. Every answer is JSON. Addresses start with https://api.postkeg.com/api/v1.
Connect your assistant
Claude, ChatGPT, Codex, Cursor and Gemini CLI can run tasks in Postkeg and help you build it into your app. They use the same API, as tools, and can read the developer docs. Pick yours and paste.
Claude
Claude app or claude.ai: Settings, Connectors, Add custom connector.
https://api.postkeg.com/mcp
Paste this address as the server URL, press Add, then Connect and approve Postkeg. On a Team or Enterprise plan an owner adds it under Admin settings, Connectors.
Claude Code
Run this in a terminal (add --scope user to have it in every project).
claude mcp add --transport http postkeg https://api.postkeg.com/mcp --header "Authorization: Bearer YOUR_API_KEY"
Replace YOUR_API_KEY with a key from Connections, API keys. Prefer signing in instead? Leave out the --header part, then run /mcp inside Claude Code and choose Authenticate.
ChatGPT
ChatGPT: Settings, Apps & Connectors, Advanced settings, turn on Developer mode, then Create.
https://api.postkeg.com/mcp
Name it Postkeg, paste this address as the MCP server URL, choose OAuth, and approve Postkeg when asked. Developer mode is not on every plan, and some plans can only read with custom connectors.
Codex
Add to ~/.codex/config.toml (or .codex/config.toml in a trusted project).
[mcp_servers.postkeg]
url = "https://api.postkeg.com/mcp"
bearer_token_env_var = "POSTKEG_API_KEY"
Put your API key in the POSTKEG_API_KEY environment variable before you start Codex; the file only names the variable.
Cursor
Save as .cursor/mcp.json in your project (or ~/.cursor/mcp.json for every project).
{
"mcpServers": {
"postkeg": {
"url": "https://api.postkeg.com/mcp",
"headers": {
"Authorization": "Bearer ${env:POSTKEG_API_KEY}"
}
}
}
}
Put your API key in the POSTKEG_API_KEY environment variable before you start Cursor; the file only names the variable.
Gemini CLI
Add to ~/.gemini/settings.json (or .gemini/settings.json in a project).
{
"mcpServers": {
"postkeg": {
"httpUrl": "https://api.postkeg.com/mcp",
"headers": {
"Authorization": "Bearer YOUR_API_KEY"
}
}
}
}
Replace YOUR_API_KEY with a key from Connections, API keys. Keep this file private.
Docs for your coding assistant
Building Postkeg into an app with Claude Code, Cursor, Codex or ChatGPT? Give it these plain-text docs (the guide, the full reference, code in curl, JavaScript, Python and PHP, and recipes). Connected assistants also get them as MCP resources.
- /llms.txt: a short index.
- /llms-full.txt: everything in one file.
Make a post
First look up the id of the channel you want to post to:
curl https://api.postkeg.com/api/v1/channels \
-H "Authorization: Bearer YOUR_API_KEY"
Then save a draft. Nothing goes out; you can see it under Posts first.
curl -X POST https://api.postkeg.com/api/v1/posts \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: 6f1c2a9e-0001" \
-H "Content-Type: application/json" \
-d '{"body": "Hello from my own code", "channel_ids": [12]}'
Postkeg publishes immediately: call the API at the time you want the post to go out and use "mode": "publish_now". Schedule on your side. A time in the future is refused (422 scheduling_not_supported). A key without the "Publish posts" permission can only save drafts.
curl -X POST https://api.postkeg.com/api/v1/posts \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: 6f1c2a9e-0002" \
-H "Content-Type: application/json" \
-d '{"body": "Launch day", "channel_ids": [12, 15], "mode": "publish_now", "media": [{"url": "https://example.com/launch.jpg", "type": "image"}]}'
Add pictures and videos
Postkeg stores no files and has no upload endpoint (POST /media answers 410). Send your media as public https links in the post's media field and keep each link valid for at least 24 hours after the call. Attachments people send you in the inbox arrive as Postkeg links that pass the file through from the network for 24 hours: download them when the webhook arrives.
Let your customers connect their own accounts
Your app makes the content; the person who owns the Instagram, TikTok or LinkedIn account only has to say yes once. Make a connect link, give them the address, and Postkeg does the rest on a small page: no Postkeg account, no password. It works for every network (sign in at the network, pick the pages or channels, or paste a key where that is how the network works).
- Register the address people should come back to (once). Only addresses on this list are ever used, so nobody can turn a link into an open redirect.
curl -X POST https://api.postkeg.com/api/v1/connect-link-redirects \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://app.example.com/connected"}'
- Make a link for one network. Your own
reference(a customer id, say) comes back to you. The key needschannels:write.
curl -X POST https://api.postkeg.com/api/v1/connect-links \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"network": "instagram", "reference": "customer-8841", "redirect_url": "https://app.example.com/connected"}'
{
"data": {
"id": 31,
"status": "pending",
"network": "instagram",
"reference": "customer-8841",
"url": "https://kairo.example/connect/Xk3...48 characters...",
"expires_at": "2026-11-22T10:00:00Z"
}
}
- Send the
urlto the account owner. It is shown only in this answer, works once, and expires after 7 days (setexpires_in_days, up to 30). It ends at the first outcome: connected, or failed (the person said no, the network refused, the plan is full). Make a new link to try again, or cancel an open one withDELETE /connect-links/{id}. - Afterwards the person lands on your return address with the outcome in the address, and you also get a webhook (
channel.connectedorchannel.connect_failed). The redirect is a convenience: trust the webhook orGET /connect-links/{id}, not the address a browser carried.
https://app.example.com/connected?status=connected&channel_id=57&reference=customer-8841&connect_link_id=31
{
"id": "evt_9a1c...",
"type": "channel.connected",
"created_at": "2026-11-15T10:04:12Z",
"workspace_id": 7,
"data": {
"connect_link": { "id": 31, "reference": "customer-8841", "network": "instagram" },
"channels": [ { "id": 57, "provider": "instagram", "name": "Shop on Instagram", "...": "the same channel the API shows" } ]
}
}
Plan limits apply: a link is refused when the workspace has no room for another channel, and the number is checked again at the network. On failure error is one of access_denied, connect_failed, plan_limit, plan_expired or too_many_attempts. Links are for the workspace that made them and nothing else.
Get the numbers back into your own dashboards
Every network reports different things; Postkeg gives you one shape. Each post has views, impressions, reach, likes, comments, shares, saves, clicks, watch_time_minutes, avg_view_duration_seconds and engagements (likes + comments + shares + saves). A number the network does not share is null, never 0, so a chart can show a gap instead of a lie. All counts are lifetime totals as of collected_at; Postkeg reads the networks about every 6 hours. Keys need analytics:read. Account numbers (followers and the like) are at GET /analytics/accounts.
One post
curl "https://api.postkeg.com/api/v1/posts/345/metrics?history=true" \
-H "Authorization: Bearer YOUR_API_KEY"
{
"data": {
"post_id": 345,
"collected_at": "2026-11-15T09:00:12Z",
"totals": { "views": 1840, "likes": 96, "comments": 7, "shares": 3, "saves": 12, "reach": null, "engagements": 118, "...": "" },
"channels": [
{ "channel_id": 57, "network": "instagram", "url": "https://www.instagram.com/p/...",
"collected_at": "2026-11-15T09:00:12Z",
"metrics": { "views": 1840, "impressions": null, "reach": null, "likes": 96, "comments": 7, "shares": 3, "saves": 12, "clicks": null, "watch_time_minutes": null, "avg_view_duration_seconds": null, "engagements": 118 } }
]
}
}
Everything, page by page
GET /analytics/posts lists every tracked post (also ones not made in Postkeg, where post_id is null). Filter with channel_id, post_id, network, published_from and, for an incremental pull, since (the time of your last pull). Follow next_cursor until has_more is false. Add format=csv for a spreadsheet-ready file (up to 1,000 rows a call, next cursor in the X-Next-Cursor header).
curl "https://api.postkeg.com/api/v1/analytics/posts?since=2026-11-14T00:00:00Z&limit=100" \
-H "Authorization: Bearer YOUR_API_KEY"
curl "https://api.postkeg.com/api/v1/analytics/posts?format=csv&limit=1000" \
-H "Authorization: Bearer YOUR_API_KEY" -D - -o posts.csv
# the next page: send the X-Next-Cursor header's value as ?cursor=
Be told instead
Subscribe a webhook to post.metrics.updated and Postkeg sends the posts whose numbers moved right after each sync, up to 50 posts a message (batch says which message of how many). Posts whose numbers did not change are not repeated.
{
"id": "evt_5b7e...",
"type": "post.metrics.updated",
"created_at": "2026-11-15T09:00:14Z",
"workspace_id": 7,
"data": {
"channel": { "id": 57, "network": "instagram", "provider": "instagram", "name": "Shop on Instagram" },
"collected_at": "2026-11-15T09:00:12Z",
"batch": { "index": 1, "of": 1 },
"posts": [
{ "post_id": 345, "channel_id": 57, "network": "instagram", "external_id": "17895...", "collected_at": "2026-11-15T09:00:12Z",
"metrics": { "views": 1840, "likes": 96, "...": "the same numbers as GET /posts/345/metrics" } }
]
}
}
Good habits
Retry safely
Add an Idempotency-Key header (any unique text, a UUID works) to a POST. If your connection drops, send the very same request with the same key: you get the first answer back (marked Idempotent-Replayed: true) and nothing is done twice. Use a new key for a new request. A request that was refused changed nothing, so you can correct it and send it again with the same key. Keys are remembered for 24 hours.
Page through long lists
Lists return data, next_cursor and has_more. Use limit (1 to 100) and pass the cursor to get the next page.
curl "https://api.postkeg.com/api/v1/posts?status=scheduled&limit=10" \
-H "Authorization: Bearer YOUR_API_KEY"
curl "https://api.postkeg.com/api/v1/posts?status=scheduled&limit=10&cursor=NEXT_CURSOR" \
-H "Authorization: Bearer YOUR_API_KEY"
When something goes wrong
Errors always look the same, with a plain message saying what to do. Quote the request_id (also in the X-Request-Id header) if you ask for help.
{
"error": {
"code": "missing_scope",
"message": "This API key does not have the posts:write scope. Create a key with it under Connections, API keys.",
"details": { "required_scope": "posts:write" },
"request_id": "req_3k2j1h0g9f8e7d6c5b4a3z2y"
}
}
- 401 the key is missing, wrong, revoked or expired.
- 402 the plan has ended: you can still read, but not change anything.
- 403 the key lacks a permission, or the person it acts as may not do this.
workspace_suspendedmeans the operator suspended publishing (reading still works). - 404 there is no such thing in this workspace.
- 409 the same Idempotency-Key was used for a different request, or the file is in use.
- 422 something in the request cannot be done;
detailssays what.duplicate_content: the same text would go to too many accounts of one network within 24 hours. - 429 too many requests: each key may make 120 a minute and 10 a second (fair use; the operator can change it). Wait for the seconds in the
Retry-Afterheader.
What a key may do
Each key carries permissions ("scopes"). A permission that changes things also includes the matching reading one.
| Scope | What it allows |
|---|---|
workspace:read |
See the workspace name, plan and who you act as. |
reddit:read |
See the communities of a Reddit account and its preferences. |
reddit:write |
Vote, save, report and join or leave communities as a connected Reddit account. |
reddit:moderate |
Use the moderator tools of communities the account moderates: remove, lock, pin, flair, mod log, mod mail, rules and wiki. Off unless the operator switched moderation on. |
linkedin:read |
See comments on any post of a LinkedIn page or profile, a page's details and its follower numbers. |
linkedin:write |
Comment and react as a LinkedIn page or profile, and delete its own comments. |
inbox:read |
See comments and direct messages on your channels (YouTube, Instagram, Facebook, Threads, LinkedIn Pages, X, Bluesky, Telegram, Discord, Slack). |
inbox:write |
Write replies (they are sent at once; they need the publish permission too) and mark comments and messages handled. |
inbox:reply_as_person |
Only for apps where a person writes each reply. Never grant to bots or automations. |
whatsapp:read |
See WhatsApp templates, contacts and broadcasts. Conversations use the inbox permissions. |
whatsapp:write |
Create and delete templates, import contacts and send broadcasts. Meta charges the business for the messages. |
facebook:read |
See a Facebook Page's profile, posts, reactions, insights, Messenger settings and Page-level webhook events. Conversations and comments use the inbox permissions. |
facebook:write |
Send rich Messenger messages (buttons, quick replies, templates), change the Page profile and Messenger settings, edit posts and comments, and block people. |
instagram:read |
See an Instagram account's own posts, stories, profile and numbers, a person's profile in a conversation, and Instagram events (reactions, button taps, live comments). |
instagram:write |
Send messages with buttons, set the ice breakers and menu, switch comments on or off, and (with Facebook Login) delete posts, like and answer collaboration invites. |
threads:read |
Browse the account's posts, replies and mentions, see insights, search, and look up locations and profiles (when allowed). Replies in the inbox use the inbox permissions. |
threads:write |
Repost, delete posts and approve or ignore pending replies. |
x:read |
Read the connected X account's bookmarks, lists, followers, following, muted and blocked accounts and its email (each needs its permission switched on for the server and allowed on the account; X charges for reads). |
x:write |
Hide replies, bookmark, repost, quote and reply, manage lists, follow, mute and block as the connected X account (X charges for each action; Postkeg passes it on). |
youtube:read |
See a YouTube channel's video details, playlists, channel sections, revenue numbers and members (each when the channel allowed it). |
youtube:write |
Change video details, manage playlists and their videos, and moderate or delete comments (each when the channel allowed it). |
analytics:read |
See how your posts and channels did (views, reach, likes, followers, best posts) and how your goals are going. |
analytics:write |
Set and remove results goals (a target for followers, views or likes of a channel). |
ads:read |
See ad accounts, campaigns, ad sets and ads, and their reports (spend, reach, clicks, results). |
ads:write |
Start and stop ads, change budgets and boost posts. The business pays the network directly. |
leads:read |
See the people who filled in your ad lead forms, with what they answered (personal data). |
leads:write |
Change the status of a lead and add notes. |
channels:read |
See your connected channels, their health and connect links. |
channels:write |
Rename and disconnect channels and make connect links. |
posts:read |
See posts, drafts, and their results. |
posts:write |
Create, edit, schedule, move, cancel, duplicate and delete posts. Without Publish posts it can only save drafts. |
posts:publish |
Schedule posts and send them out straight away, retry failed ones, publish replies. Without it only drafts can be saved. |
media:read |
Postkeg stores no files, so nothing is left to see with this. It is only kept so keys that have it keep working. |
media:write |
Postkeg stores no files, so there is nothing to manage with this. It is only kept so keys that have it keep working. |
webhooks:read |
See the addresses Postkeg sends events to. |
webhooks:write |
Add and delete the addresses Postkeg sends events to. |
automations:read |
See your automations (rules and journeys that answer comments and messages), the people in journeys and what they did. |
automations:write |
Create, change, switch on and off and delete automations, and take people out of journeys. Their replies are only sent when the key or connection holds the publish permission. |
Everything you can call
The full, machine-readable description is at /api/v1/openapi.json (OpenAPI 3.1): import it into Postman, Insomnia or a code generator.
Workspace
| Call | Needs | What it does |
|---|---|---|
GET /me |
workspace:read |
Who this key is |
GET /plan |
workspace:read |
Plan and usage |
GET /billing |
workspace:read |
Subscription status |
GET /wallet |
workspace:read |
X balance |
GET /wallet/entries |
workspace:read |
X balance ledger |
POST /wallet/top-ups |
workspace:read |
Top up the X balance |
Posts
| Call | Needs | What it does |
|---|---|---|
GET /posts |
posts:read |
List posts |
POST /posts |
posts:write |
Create a post |
POST /posts/bulk |
posts:write |
Create up to 100 posts |
GET /posts/{post} |
posts:read |
Get a post |
PATCH /posts/{post} |
posts:write |
Change a post |
POST /posts/{post}/move |
posts:write |
Set a time for a post |
POST /posts/{post}/cancel |
posts:write |
Cancel a post |
POST /posts/by-external-id/{external_id}/cancel |
posts:write |
Cancel a post by external_id |
DELETE /posts/by-external-id/{external_id} |
posts:write |
Delete a post by external_id |
POST /posts/{post}/duplicate |
posts:write |
Duplicate a post |
DELETE /posts/{post} |
posts:write |
Delete a post |
POST /posts/{post}/publish |
posts:publish |
Publish a post now |
PATCH /posts/{post}/channels/{channel} |
posts:publish |
Edit a published post on one network |
DELETE /posts/{post}/channels/{channel} |
posts:publish |
Delete a post from one network |
POST /posts/{post}/channels/{channel}/retry |
posts:publish |
Retry a failed channel |
Channels
| Call | Needs | What it does |
|---|---|---|
GET /channels |
channels:read |
List channels |
GET /channels/{channel} |
channels:read |
Get a channel |
PATCH /channels/{channel} |
channels:write |
Rename a channel, tag it with a tenant, or switch X reading |
DELETE /channels/{channel} |
channels:write |
Disconnect a channel |
POST /channels |
channels:write |
Make a test channel (test keys only) |
POST /connect-links |
channels:write |
Make a connect link |
GET /connect-links |
channels:read |
List connect links |
GET /connect-links/{link} |
channels:read |
Get a connect link |
DELETE /connect-links/{link} |
channels:write |
Cancel a connect link |
GET /connect-link-redirects |
channels:read |
List return addresses |
POST /connect-link-redirects |
channels:write |
Add a return address |
DELETE /connect-link-redirects/{redirect} |
channels:write |
Remove a return address |
Inbox
| Call | Needs | What it does |
|---|---|---|
GET /inbox/threads |
inbox:read |
List comment threads |
GET /inbox/counts |
inbox:read |
Count open and unread threads |
GET /inbox/accounts |
inbox:read |
What each channel can do in the inbox |
GET /inbox/messages |
inbox:read |
List stored messages |
POST /inbox/messages/{message}/actions |
inbox:write |
Hide, show, delete or like a message |
GET /inbox/threads/{thread} |
inbox:read |
Get a thread |
POST /inbox/threads/{thread}/replies |
inbox:write |
Reply to a thread |
POST /inbox/read-all |
inbox:write |
Mark everything read |
POST /inbox/threads/{thread}/read |
inbox:write |
Mark a thread read or unread |
POST /inbox/threads/{thread}/handled |
inbox:write |
Mark a thread handled |
POST /inbox/threads/{thread}/moderation |
inbox:write |
Hide, show, delete or like a comment |
Events
| Call | Needs | What it does |
|---|---|---|
GET /events |
workspace:read |
Poll events |
GET /events/stream |
workspace:read |
Stream events (Server-Sent Events) |
POST /events/stream-tokens |
workspace:read |
Make a stream token |
Automations
| Call | Needs | What it does |
|---|---|---|
GET /automations |
automations:read |
List automations |
POST /automations |
automations:write |
Create an automation |
GET /automations/{automation} |
automations:read |
Get an automation |
PATCH /automations/{automation} |
automations:write |
Change an automation |
DELETE /automations/{automation} |
automations:write |
Delete an automation |
GET /automations/{automation}/runs |
automations:read |
Log of an automation |
GET /journeys |
automations:read |
List journeys |
POST /journeys |
automations:write |
Create a journey |
GET /journeys/{journey} |
automations:read |
Get a journey |
PATCH /journeys/{journey} |
automations:write |
Change a journey |
DELETE /journeys/{journey} |
automations:write |
Delete a journey |
GET /journeys/{journey}/runs |
automations:read |
People in a journey |
GET /journeys/{journey}/log |
automations:read |
Log of a journey |
DELETE /journeys/{journey}/runs/{run} |
automations:write |
Take a person out of a journey |
Analytics
| Call | Needs | What it does |
|---|---|---|
GET /posts/{post}/metrics |
analytics:read |
Numbers of one post |
GET /analytics/posts |
analytics:read |
Export numbers of all posts |
GET /analytics/accounts |
analytics:read |
Followers and account numbers per channel |
GET /analytics/accounts/{channel}/history |
analytics:read |
Daily history of one channel |
GET /goals |
analytics:read |
List goals |
POST /goals |
analytics:write |
Set a goal |
DELETE /goals/{goal} |
analytics:write |
Delete a goal |
Leads
| Call | Needs | What it does |
|---|---|---|
GET /leads |
leads:read |
List leads |
GET /leads/{lead} |
leads:read |
Get a lead |
PATCH /leads/{lead} |
leads:write |
Change a lead |
DELETE /leads/{lead} |
leads:write |
Delete a lead |
Ads
| Call | Needs | What it does |
|---|---|---|
GET /ad-accounts |
ads:read |
List ad accounts |
GET /ad-accounts/{adAccount} |
ads:read |
Get an ad account |
DELETE /ad-accounts/{adAccount} |
ads:write |
Disconnect an ad account |
POST /ad-connect-links |
ads:write |
Make an ad connect link |
GET /ad-connect-links/{link} |
ads:read |
Get an ad connect link |
GET /ad-accounts/{adAccount}/objects |
ads:read |
List campaigns, ad sets or ads |
GET /ad-accounts/{adAccount}/locations |
ads:read |
Search places for a boost |
GET /ad-accounts/{adAccount}/catalogs |
ads:read |
List product catalogs |
POST /ad-accounts/{adAccount}/catalogs |
ads:write |
Make a product catalog |
GET /ad-accounts/{adAccount}/catalogs/feeds |
ads:read |
List product feeds |
POST /ad-accounts/{adAccount}/catalogs/feeds |
ads:write |
Make a product feed |
PATCH /ad-accounts/{adAccount}/catalogs/feeds/{feed} |
ads:write |
Change a product feed |
DELETE /ad-accounts/{adAccount}/catalogs/feeds/{feed} |
ads:write |
Delete a product feed |
POST /ad-accounts/{adAccount}/catalogs/feeds/{feed}/ingest |
ads:write |
Fetch a product feed now |
GET /ad-accounts/{adAccount}/catalogs/feeds/{feed}/processing-results |
ads:read |
Product feed processing results |
GET /ad-accounts/{adAccount}/insights |
ads:read |
Report on campaigns, ad sets or ads |
PATCH /ad-accounts/{adAccount}/objects/{object} |
ads:write |
Pause, resume or change a budget |
POST /ad-accounts/{adAccount}/boosts |
ads:write |
Boost a published post |
Webhooks
| Call | Needs | What it does |
|---|---|---|
GET /webhooks |
webhooks:read |
List webhooks |
POST /webhooks |
webhooks:write |
Add a webhook |
PATCH /webhooks/{webhook} |
webhooks:write |
Rename a Postcraft link |
GET /webhooks/{webhook}/deliveries |
webhooks:read |
List deliveries of a webhook |
POST /webhooks/deliveries/{delivery}/redeliver |
webhooks:write |
Send an event again |
DELETE /webhooks/{webhook} |
webhooks:write |
Delete a webhook |
| Call | Needs | What it does |
|---|---|---|
GET /whatsapp/numbers |
whatsapp:read |
List WhatsApp numbers |
GET /whatsapp/templates |
whatsapp:read |
List templates |
GET /whatsapp/templates/{template} |
whatsapp:read |
Get a template |
POST /whatsapp/templates |
whatsapp:write |
Create a template |
PATCH /whatsapp/templates/{template} |
whatsapp:write |
Edit a template |
POST /whatsapp/templates/sync |
whatsapp:write |
Reload templates from Meta |
DELETE /whatsapp/templates/{template} |
whatsapp:write |
Delete a template |
GET /whatsapp/contacts |
whatsapp:read |
List contacts |
POST /whatsapp/contacts |
whatsapp:write |
Add or update a contact |
POST /whatsapp/contacts/import |
whatsapp:write |
Import contacts from CSV |
PATCH /whatsapp/contacts/{contact} |
whatsapp:write |
Change a contact |
DELETE /whatsapp/contacts/{contact} |
whatsapp:write |
Remove a contact |
GET /whatsapp/broadcasts |
whatsapp:read |
List broadcasts |
POST /whatsapp/broadcasts |
whatsapp:write |
Create a broadcast |
POST /whatsapp/broadcasts/estimate |
whatsapp:read |
Estimate a broadcast |
GET /whatsapp/broadcasts/{broadcast} |
whatsapp:read |
Get a broadcast |
POST /whatsapp/broadcasts/{broadcast}/cancel |
whatsapp:write |
Cancel a broadcast |
GET /whatsapp/broadcasts/{broadcast}/recipients |
whatsapp:read |
List recipients |
POST /whatsapp/numbers/{channel}/messages |
whatsapp:write |
Send a message of any type |
POST /whatsapp/numbers/{channel}/typing |
whatsapp:write |
Show the typing indicator |
GET /whatsapp/messages/payloads |
whatsapp:read |
List structured inbound data |
POST /whatsapp/numbers/{channel}/media |
whatsapp:write |
Upload media |
DELETE /whatsapp/numbers/{channel}/media/{media} |
whatsapp:write |
Delete uploaded media |
GET /whatsapp/numbers/{channel}/profile |
whatsapp:read |
Get the business profile |
PATCH /whatsapp/numbers/{channel}/profile |
whatsapp:write |
Change the business profile |
GET /whatsapp/numbers/{channel}/qr-codes |
whatsapp:read |
List QR codes and message links |
POST /whatsapp/numbers/{channel}/qr-codes |
whatsapp:write |
Create a QR code |
PATCH /whatsapp/numbers/{channel}/qr-codes/{code} |
whatsapp:write |
Change a QR code |
DELETE /whatsapp/numbers/{channel}/qr-codes/{code} |
whatsapp:write |
Delete a QR code |
GET /whatsapp/numbers/{channel}/blocks |
whatsapp:read |
List blocked people |
POST /whatsapp/numbers/{channel}/blocks |
whatsapp:write |
Block people |
DELETE /whatsapp/numbers/{channel}/blocks |
whatsapp:write |
Unblock people |
GET /whatsapp/numbers/{channel}/commerce |
whatsapp:read |
Commerce settings and catalogs |
PATCH /whatsapp/numbers/{channel}/commerce |
whatsapp:write |
Change commerce settings |
GET /whatsapp/flows |
whatsapp:read |
List Flows |
POST /whatsapp/flows |
whatsapp:write |
Create a Flow |
POST /whatsapp/flows/{flow}/publish |
whatsapp:write |
Publish a Flow |
POST /whatsapp/flows/{flow}/deprecate |
whatsapp:write |
Deprecate a Flow |
DELETE /whatsapp/flows/{flow} |
whatsapp:write |
Delete a draft Flow |
POST /whatsapp/numbers/{channel}/direct-send |
whatsapp:write |
Direct Send (utility) |
GET /whatsapp/numbers/{channel}/marketing-messages |
whatsapp:read |
Marketing Messages API state |
POST /whatsapp/numbers/{channel}/marketing-messages/check |
whatsapp:write |
Check Marketing Messages API onboarding |
POST /whatsapp/numbers/{channel}/marketing-messages/send |
whatsapp:write |
Send a marketing template through the Marketing Messages API |
GET /whatsapp/numbers/{channel}/settings |
whatsapp:read |
Number settings |
POST /whatsapp/numbers/{channel}/two-step-pin |
whatsapp:write |
Set or change the two-step verification PIN |
POST /whatsapp/numbers/{channel}/display-name |
whatsapp:write |
Ask for a new display name |
POST /whatsapp/numbers/{channel}/verification-code |
whatsapp:write |
Request a verification code |
POST /whatsapp/numbers/{channel}/verify-code |
whatsapp:write |
Verify the code |
POST /whatsapp/numbers/{channel}/identity-check |
whatsapp:write |
Identity change check |
POST /whatsapp/numbers/{channel}/template-assets |
whatsapp:write |
Upload a template header sample |
GET /whatsapp/numbers/{channel}/flow-endpoint |
whatsapp:read |
Flow data-exchange endpoint |
POST /whatsapp/numbers/{channel}/flow-endpoint |
whatsapp:write |
Create or change the Flow endpoint |
POST /whatsapp/numbers/{channel}/flow-endpoint/check |
whatsapp:write |
Check the Flow endpoint key |
DELETE /whatsapp/numbers/{channel}/flow-endpoint |
whatsapp:write |
Remove the Flow endpoint |
POST /whatsapp/numbers/{channel}/conversion-events |
whatsapp:write |
Send a conversion event to Meta |
GET /whatsapp/analytics/messaging |
whatsapp:read |
Messaging analytics |
GET /whatsapp/analytics/pricing |
whatsapp:read |
Pricing analytics |
GET /whatsapp/analytics/templates |
whatsapp:read |
Template analytics |
| Call | Needs | What it does |
|---|---|---|
POST /facebook/{channel}/messages |
facebook:write |
Send a Messenger message |
POST /facebook/{channel}/messages/react |
facebook:write |
React to a Messenger message |
POST /facebook/{channel}/typing |
facebook:write |
Show typing or mark as seen |
POST /facebook/{channel}/attachments |
facebook:write |
Upload a reusable attachment |
GET /facebook/{channel}/personas |
facebook:read |
List personas |
POST /facebook/{channel}/personas |
facebook:write |
Create a persona |
DELETE /facebook/{channel}/personas/{persona} |
facebook:write |
Delete a persona |
GET /facebook/{channel}/messenger-profile |
facebook:read |
Read the Messenger profile |
PUT /facebook/{channel}/messenger-profile |
facebook:write |
Change the Messenger profile |
DELETE /facebook/{channel}/messenger-profile |
facebook:write |
Remove Messenger profile fields |
GET /facebook/{channel}/messaging-features |
facebook:read |
Messaging features Meta approved |
GET /facebook/{channel}/profile |
facebook:read |
Read the Page profile |
PATCH /facebook/{channel}/profile |
facebook:write |
Change the Page profile |
GET /facebook/{channel}/posts |
facebook:read |
Browse the Page's posts |
GET /facebook/{channel}/public-pages/{page} |
facebook:read |
Read another public Page |
GET /facebook/{channel}/public-pages/{page}/posts |
facebook:read |
Recent posts of another public Page |
POST /facebook/{channel}/posts/{post} |
facebook:write |
Edit a post's text |
GET /facebook/{channel}/reactions |
facebook:read |
Reactions on a post or comment |
GET /facebook/{channel}/insights |
facebook:read |
Page and post insights |
GET /facebook/{channel}/integrity |
facebook:read |
Page integrity status |
POST /facebook/{channel}/blocked |
facebook:write |
Block a person on the Page |
DELETE /facebook/{channel}/blocked |
facebook:write |
Unblock a person |
POST /facebook/{channel}/comments/{comment} |
facebook:write |
Edit a comment the Page wrote |
POST /facebook/{channel}/comments/{comment}/replies |
facebook:write |
Reply to a comment, with a picture or GIF |
GET /facebook/{channel}/videos/{video} |
facebook:read |
Read a Page video |
POST /facebook/{channel}/videos/{video} |
facebook:write |
Change a video's title or description |
POST /facebook/{channel}/videos/{video}/thumbnail |
facebook:write |
Add a custom video thumbnail |
GET /facebook/{channel}/videos/{video}/captions |
facebook:read |
List a video's captions |
POST /facebook/{channel}/videos/{video}/captions |
facebook:write |
Upload SRT captions |
DELETE /facebook/{channel}/videos/{video}/captions |
facebook:write |
Delete captions of one locale |
POST /facebook/{channel}/videos/{video}/crosspost |
facebook:write |
Crosspost a video to other Pages |
GET /facebook/{channel}/thread-owner |
facebook:read |
Which app controls a Messenger thread |
POST /facebook/{channel}/thread-control |
facebook:write |
Pass, take, request, release or extend thread control |
GET /facebook/{channel}/notifications |
facebook:read |
Notification messages opt-ins |
POST /facebook/{channel}/notifications/request |
facebook:write |
Ask a person to opt in to notifications |
POST /facebook/{channel}/notifications/send |
facebook:write |
Send a notification |
GET /facebook/{channel}/templates |
facebook:read |
List Messenger utility templates |
POST /facebook/{channel}/templates |
facebook:write |
Create a Messenger utility template |
POST /facebook/{channel}/templates/send |
facebook:write |
Send a Messenger utility template |
GET /facebook/{channel}/live-videos |
facebook:read |
List the Page's live videos |
POST /facebook/{channel}/live-videos |
facebook:write |
Create a live video |
POST /facebook/{channel}/live-videos/{video}/end |
facebook:write |
End a live video |
GET /facebook/{channel}/call-to-action |
facebook:read |
Read the Page's call-to-action button |
PUT /facebook/{channel}/call-to-action |
facebook:write |
Set the Page's call-to-action button |
DELETE /facebook/{channel}/call-to-action/{cta} |
facebook:write |
Remove the Page's call-to-action button |
POST /facebook/{channel}/webhook-subscription |
facebook:write |
Subscribe the Page to every webhook field |
| Call | Needs | What it does |
|---|---|---|
GET /instagram/{channel}/profile |
instagram:read |
Read the account's profile |
GET /instagram/{channel}/media |
instagram:read |
List the account's own media |
GET /instagram/{channel}/media/{media} |
instagram:read |
Read one media |
GET /instagram/{channel}/insights |
instagram:read |
Read Instagram insights |
POST /instagram/{channel}/media/{media} |
instagram:write |
Switch comments on or off |
DELETE /instagram/{channel}/media/{media} |
instagram:write |
Delete a post, Reel or story |
GET /instagram/{channel}/users/{igsid} |
instagram:read |
Read a person's profile |
POST /instagram/{channel}/messages |
instagram:write |
Send a message |
POST /instagram/{channel}/typing |
instagram:write |
Show typing or mark as read |
POST /instagram/{channel}/reactions |
instagram:write |
React to a message |
GET /instagram/{channel}/messenger-profile |
instagram:read |
Read ice breakers and the menu |
PUT /instagram/{channel}/messenger-profile |
instagram:write |
Set ice breakers and the menu |
DELETE /instagram/{channel}/messenger-profile |
instagram:write |
Remove ice breakers or the menu |
POST /instagram/{channel}/conversations/{igsid}/moderation |
instagram:write |
Block, unblock or mark a conversation as spam |
POST /instagram/{channel}/likes |
instagram:write |
Like a post or comment |
DELETE /instagram/{channel}/likes |
instagram:write |
Remove a like |
GET /instagram/{channel}/tags |
instagram:read |
Posts the account is tagged in |
GET /instagram/{channel}/collaboration-invites |
instagram:read |
List collaboration invites |
POST /instagram/{channel}/collaboration-invites/{media} |
instagram:write |
Accept or decline an invite |
GET /instagram/{channel}/discover |
instagram:read |
Look up another business account |
GET /instagram/{channel}/hashtags |
instagram:read |
Find a hashtag id |
GET /instagram/{channel}/hashtags/{hashtag}/media |
instagram:read |
Posts of a hashtag |
GET /instagram/{channel}/locations |
instagram:read |
Find a place to tag |
GET /instagram/{channel}/catalogs |
instagram:read |
List product catalogs to tag from |
GET /instagram/{channel}/catalogs/products |
instagram:read |
Find a product to tag |
GET /instagram/{channel}/branded-content/creators |
instagram:read |
List the creators a brand approved |
POST /instagram/{channel}/branded-content/creators |
instagram:write |
Approve creators for branded content |
DELETE /instagram/{channel}/branded-content/creators |
instagram:write |
Remove approved creators |
GET /instagram/oembed |
instagram:read |
Embed code of a public post |
Threads
| Call | Needs | What it does |
|---|---|---|
GET /threads/{channel}/posts |
threads:read |
List the account's posts |
GET /threads/{channel}/posts/{external_id} |
threads:read |
Get a post |
GET /threads/{channel}/replies |
threads:read |
List the account's own replies |
GET /threads/{channel}/mentions |
threads:read |
List mentions |
GET /threads/{channel}/ghost-posts |
threads:read |
List ghost posts |
GET /threads/{channel}/posts/{external_id}/pending-replies |
threads:read |
List pending replies |
POST /threads/{channel}/pending-replies/{external_id}/approve |
threads:write |
Approve a pending reply |
POST /threads/{channel}/pending-replies/{external_id}/ignore |
threads:write |
Ignore a pending reply |
POST /threads/{channel}/posts/{external_id}/repost |
threads:write |
Repost a post |
DELETE /threads/{channel}/posts/{external_id} |
threads:write |
Delete a post or repost |
GET /threads/{channel}/insights |
threads:read |
Read insights |
GET /threads/{channel}/locations |
threads:read |
Search locations |
GET /threads/{channel}/search |
threads:read |
Search public posts |
GET /threads/{channel}/profile |
threads:read |
Look up a public profile |
GET /threads/oembed |
threads:read |
Get embed code |
GET /threads/trending |
threads:read |
List trending topics |
GET /threads/trending/{external_id}/posts |
threads:read |
List posts of a trend |
| Call | Needs | What it does |
|---|---|---|
GET /reddit/{channel}/subreddits |
reddit:read |
List the account's communities |
GET /reddit/{channel}/prefs |
reddit:read |
Read the account's preferences |
POST /reddit/{channel}/things/{thing}/vote |
reddit:write |
Upvote, downvote or take a vote back |
POST /reddit/{channel}/things/{thing}/save |
reddit:write |
Save or unsave a post or comment |
POST /reddit/{channel}/things/{thing}/report |
reddit:write |
Report a post or comment |
PUT /reddit/{channel}/subreddits/{subreddit}/subscription |
reddit:write |
Join or leave a community |
POST /reddit/{channel}/things/{thing}/moderation |
reddit:moderate |
Moderate a post or comment |
POST /reddit/{channel}/subreddits/{subreddit}/flair |
reddit:moderate |
Set the flair of a post or user |
GET /reddit/{channel}/subreddits/{subreddit}/modlog |
reddit:moderate |
Read the moderation log |
GET /reddit/{channel}/modmail/conversations |
reddit:moderate |
List mod mail conversations |
GET /reddit/{channel}/modmail/conversations/{conversation} |
reddit:moderate |
Read a mod mail conversation |
POST /reddit/{channel}/modmail/conversations/{conversation}/replies |
reddit:moderate |
Reply in a mod mail conversation |
GET /reddit/{channel}/subreddits/{subreddit}/config |
reddit:moderate |
Read a community's rules and settings |
GET /reddit/{channel}/subreddits/{subreddit}/wiki/{page} |
reddit:moderate |
Read a wiki page |
PUT /reddit/{channel}/subreddits/{subreddit}/wiki/{page} |
reddit:moderate |
Edit a wiki page |
| Call | Needs | What it does |
|---|---|---|
GET /linkedin/{channel}/posts/{post}/comments |
linkedin:read |
List the comments of a post |
POST /linkedin/{channel}/posts/{post}/comments |
linkedin:write |
Comment on a post |
DELETE /linkedin/{channel}/posts/{post}/comments/{comment} |
linkedin:write |
Delete a comment the channel wrote |
PUT /linkedin/{channel}/reactions |
linkedin:write |
React to a post or comment |
GET /linkedin/{channel}/organization |
linkedin:read |
Read the company page's details |
GET /linkedin/{channel}/followers |
linkedin:read |
Follower count and gains of a company page |
X
| Call | Needs | What it does |
|---|---|---|
GET /x/{channel}/account |
x:read |
Get the account and its email |
GET /x/{channel}/bookmarks |
x:read |
List bookmarks |
GET /x/{channel}/lists |
x:read |
List the account's own lists |
GET /x/{channel}/lists/{list} |
x:read |
Get a list |
GET /x/{channel}/lists/{list}/members |
x:read |
List the members of a list |
GET /x/{channel}/lists/{list}/posts |
x:read |
List the posts of a list |
GET /x/{channel}/followers |
x:read |
List followers |
GET /x/{channel}/following |
x:read |
List who the account follows |
GET /x/{channel}/muted |
x:read |
List muted accounts |
GET /x/{channel}/blocked |
x:read |
List blocked accounts |
POST /x/{channel}/posts/{post}/hide |
x:write |
Hide a reply |
POST /x/{channel}/posts/{post}/unhide |
x:write |
Show a hidden reply again |
POST /x/{channel}/posts/{post}/bookmark |
x:write |
Bookmark a post |
DELETE /x/{channel}/posts/{post}/bookmark |
x:write |
Remove a bookmark |
POST /x/{channel}/posts/{post}/repost |
x:write |
Repost a post |
DELETE /x/{channel}/posts/{post}/repost |
x:write |
Take back a repost |
POST /x/{channel}/quotes |
x:write |
Quote a post |
POST /x/{channel}/replies |
x:write |
Reply to a post |
POST /x/{channel}/lists |
x:write |
Create a list |
PATCH /x/{channel}/lists/{list} |
x:write |
Change a list |
DELETE /x/{channel}/lists/{list} |
x:write |
Delete a list |
POST /x/{channel}/lists/{list}/members |
x:write |
Add a list member |
DELETE /x/{channel}/lists/{list}/members/{user} |
x:write |
Remove a list member |
POST /x/{channel}/follows |
x:write |
Follow a person |
DELETE /x/{channel}/follows/{user} |
x:write |
Unfollow a person |
POST /x/{channel}/mutes |
x:write |
Mute a person |
DELETE /x/{channel}/mutes/{user} |
x:write |
Unmute a person |
POST /x/{channel}/blocks |
x:write |
Block a person |
DELETE /x/{channel}/blocks/{user} |
x:write |
Unblock a person |
YouTube
| Call | Needs | What it does |
|---|---|---|
GET /youtube/{channel}/videos/{video} |
youtube:read |
Read a video |
PATCH /youtube/{channel}/videos/{video} |
youtube:write |
Change a video's details |
POST /youtube/{channel}/videos/{video}/thumbnail |
youtube:write |
Set a custom thumbnail from a link |
GET /youtube/{channel}/playlists |
youtube:read |
List playlists |
POST /youtube/{channel}/playlists |
youtube:write |
Create a playlist |
PATCH /youtube/{channel}/playlists/{playlist} |
youtube:write |
Change a playlist |
DELETE /youtube/{channel}/playlists/{playlist} |
youtube:write |
Delete a playlist |
GET /youtube/{channel}/playlists/{playlist}/items |
youtube:read |
List a playlist's videos |
POST /youtube/{channel}/playlists/{playlist}/items |
youtube:write |
Add a video to a playlist |
DELETE /youtube/{channel}/playlists/{playlist}/items/{item} |
youtube:write |
Remove a video from a playlist |
POST /youtube/{channel}/comments/moderate |
youtube:write |
Hold, publish or reject comments |
DELETE /youtube/{channel}/comments/{comment} |
youtube:write |
Delete a comment |
GET /youtube/{channel}/sections |
youtube:read |
Read the channel's homepage sections |
GET /youtube/{channel}/revenue |
youtube:read |
Revenue numbers |
GET /youtube/{channel}/membership-levels |
youtube:read |
List membership levels |
GET /youtube/{channel}/members |
youtube:read |
List channel members |
Webhooks: hear about posts without asking
Instead of asking again and again whether a post went out, give Postkeg an address and it tells you. Add one under
Connections, Webhooks.
The address must start with https://.
Postkeg announces every change, so you can automate from them. Tick the ones you want when you add the webhook, or use a whole group such as inbox.* (or * for everything). Every event with its full message is in the webhooks document and the OpenAPI description.
whatsapp.message.status- A WhatsApp message changed state.
whatsapp.template.status- A WhatsApp template changed state.
whatsapp.broadcast.finished- A WhatsApp broadcast finished.
whatsapp.contact.opted_out- A WhatsApp contact opted out.
whatsapp.message.payload- A WhatsApp message carried structured data.
whatsapp.template.quality- A WhatsApp template quality changed.
whatsapp.account.alert- A WhatsApp account alert.
whatsapp.account.review- A WhatsApp account review decision.
whatsapp.phone.name- A WhatsApp display name decision.
whatsapp.contact.preference- A WhatsApp person changed their marketing preference.
whatsapp.contact.identity- A WhatsApp person changed their number or user id.
whatsapp.account.security- A WhatsApp two-step verification event.
whatsapp.account.capability- A WhatsApp business limit changed.
whatsapp.template.components- A WhatsApp template's content changed.
whatsapp.partner.solution- A WhatsApp partner solution changed.
whatsapp.automatic_event- A WhatsApp ad conversion event.
whatsapp.payment.configuration- A WhatsApp payment configuration changed.
whatsapp.handover- A WhatsApp conversation changed owner.
whatsapp.flow.status- A WhatsApp Flow changed or its endpoint health changed.
whatsapp.flow.error- A WhatsApp Flow reported an error to the data-exchange endpoint.
whatsapp.phone.quality- A WhatsApp number's limit or throughput changed.
whatsapp.marketing_messages.status- A WhatsApp number's Marketing Messages API state changed.
messenger.delivery- A Messenger message was delivered.
messenger.read- A Messenger message was read.
messenger.reaction- Somebody reacted to a Messenger message.
messenger.postback- A Messenger button was pressed.
messenger.referral- A Messenger conversation started from a link or ad.
messenger.optin- Somebody opted in on Messenger.
messenger.feedback- A person rated an answer on Messenger.
messenger.policy- Meta warned or blocked the Page's messaging.
facebook.page.integrity- The Page's integrity status changed.
facebook.video.status- A Page video changed processing status.
facebook.live_video.status- A Page live video changed status.
facebook.conversation.updated- A Page conversation changed.
facebook.publisher_subscription- A Page publisher subscription changed.
facebook.page_change_proposal- Meta proposed a change to the Page.
messenger.handover- Messenger thread control changed.
messenger.standby- A conversation event arrived while another app owns the thread.
messenger.template.status- A Messenger utility template changed status.
facebook.feed.post- Page feed: post.
facebook.feed.status- Page feed: status.
facebook.feed.photo- Page feed: photo.
facebook.feed.video- Page feed: video.
facebook.feed.share- Page feed: share.
facebook.feed.reaction- Page feed: reaction.
instagram.message.reaction- An Instagram message got a reaction.
instagram.message.seen- An Instagram message was read.
instagram.message.postback- An Instagram button or ice breaker was tapped.
instagram.message.referral- An Instagram conversation started from a link.
instagram.message.optin- An Instagram person opted in to messages.
instagram.handover- Another app took or gave back an Instagram conversation.
instagram.standby- An Instagram message arrived while another app owns the conversation.
instagram.live_comment- A comment on an Instagram live video.
instagram.story.insights- Numbers of an Instagram story that just ended.
threads.post.published- A Threads post was published.
threads.post.deleted- A Threads post was deleted.
post.created- A post was created.
post.updated- A post was changed.
post.scheduled- A post was scheduled.
post.cancelled- A post was cancelled.
post.published- A post went out.
post.partially_published- A post went out on some channels.
post.failed- A post failed.
post.rejected- A network refused a post.
post.deleted- A post was deleted.
post.metrics.updated- Post numbers changed.
channel.connected- An account was connected.
channel.connect_failed- Connecting an account failed.
channel.reconnected- A channel works again.
channel.needs_reconnect- A channel needs to be reconnected.
channel.token_expiring- A channel connection ends soon.
channel.x_reading.limit- An X account reached its reading allowance.
channel.disconnected- A channel was disconnected.
inbox.item.received- An item arrived.
inbox.item.updated- An item was edited.
inbox.item.deleted- An item was deleted.
inbox.thread.handled- A conversation was marked handled.
inbox.thread.read- A conversation was read.
inbox.threads.read- Many conversations were marked read.
inbox.comment.hidden- A comment was hidden.
inbox.comment.unhidden- A comment was shown again.
inbox.comment.deleted- A comment was deleted.
inbox.reply.sent- A reply went out.
inbox.reply.failed- A reply could not be sent.
inbox.dm_window.closing- A message window closes soon.
ad_account.connected- An ad account was connected.
ad_account.disconnected- An ad account was disconnected.
ad_account.needs_reconnect- An ad account needs to be reconnected.
ad.boost.started- A boost started.
ad.boost.failed- A boost failed.
ad.boost.finished- A boost finished.
ad.status_changed- An ad was paused or resumed.
ad.budget_changed- A budget was changed.
lead.received- A lead arrived.
account.goal_reached- A goal was reached.
billing.subscription.updated- The subscription changed.
wallet.balance.low- The X balance is running low.
wallet.balance.empty- An X charge was refused: balance too low.
wallet.topped_up- The X balance was topped up.
workspace.allowance.reached- An account reached its monthly allowance.
workspace.publishing.paused- Publishing was paused.
workspace.publishing.resumed- Publishing resumed.
automation.run- An automation ran.
journey.started- A journey started.
journey.step- A journey step ran.
journey.completed- A journey ended well.
journey.failed- A journey failed.
journey.ai_requested- Your AI was asked.
Each message is a small JSON document:
{
"id": "evt_4f9a1c2b7d8e0f3a5b6c7d8e",
"type": "post.published",
"created_at": "2026-11-12T08:30:04Z",
"workspace_id": 7,
"data": { "post": { "id": 345, "status": "published", "...": "the same post the API shows" } }
}
Check that it really came from Postkeg
Every message has an X-Postkeg-Signature header: v1= followed by an HMAC-SHA256 (hex) of the timestamp, a dot and the raw body, made with the signing secret you saw when you added the webhook. The timestamp is in X-Postkeg-Timestamp (seconds). Refuse a message whose timestamp is more than 5 minutes old, so a copy someone captured cannot be sent again later. Other headers: X-Postkeg-Event, X-Postkeg-Event-Id (the same on a resend: keep ids to skip repeats) and X-Postkeg-Attempt.
<?php
$secret = getenv('POSTKEG_WEBHOOK_SECRET'); // whsec_...
$body = file_get_contents('php://input'); // the raw text, before decoding
$timestamp = $_SERVER['HTTP_X_POSTKEG_TIMESTAMP'] ?? '';
$signature = $_SERVER['HTTP_X_POSTKEG_SIGNATURE'] ?? '';
$expected = 'v1=' . hash_hmac('sha256', $timestamp . '.' . $body, $secret);
if (!ctype_digit($timestamp) || abs(time() - (int) $timestamp) > 300
|| !hash_equals($expected, $signature)) {
http_response_code(401);
exit;
}
$event = json_decode($body, true);
// Skip it if you already handled $event['id'], do your work, then:
http_response_code(200);
import crypto from 'node:crypto';
// Express: use express.raw({ type: 'application/json' }) so req.body is the raw text.
export function isFromPostkeg(req, secret) {
const timestamp = req.get('X-Postkeg-Timestamp') ?? '';
const signature = req.get('X-Postkeg-Signature') ?? '';
const body = req.body.toString('utf8');
const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) <= 300;
const expected = 'v1=' + crypto.createHmac('sha256', secret).update(timestamp + '.' + body).digest('hex');
const a = Buffer.from(expected);
const b = Buffer.from(signature);
return fresh && a.length === b.length && crypto.timingSafeEqual(a, b);
}
import hmac, hashlib, time
def is_from_postkeg(raw_body: bytes, timestamp: str, signature: str, secret: str) -> bool:
if not timestamp.isdigit() or abs(time.time() - int(timestamp)) > 300:
return False
signed = timestamp.encode() + b'.' + raw_body
expected = 'v1=' + hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, signature)
What Postkeg does when you do not answer
Answer with any 2xx status within 5 seconds. Otherwise Postkeg tries again after 1 minute, 5 minutes, 30 minutes and 6 hours: five tries in all. Redirects are not followed, so give the final address. If several events in a row cannot be delivered, the webhook is switched off and the owner gets an email; fix the address and switch it on again. The page lists every delivery and lets you send one again, or send a test.
The delivery log, and sending again
Postkeg keeps every delivery and every try for 30 days, with the answer code, how long your server took and the start of its answer. Read it with GET /webhooks/{id}/deliveries and send an event again with POST /webhooks/deliveries/{id}/redeliver (it keeps the same event id). A webhook that has failed for 3 days is switched off too.