Automate Postocial with the REST API and webhooks

Last updated November 1, 2026

What you can build on

• Publishing API: accounts, posts, scheduling, approvals, media, tags and analytics.
• Messaging API: contacts, conversations, messages, segments, broadcasts, automations, channels and media, for messaging on Premium and higher plans.
• Link in Bio API, for building on your bio pages on Premium and higher plans.

The full reference is in the API documentation. For an overview of everything developers can use, see API and MCP.

Create an API key

1. Open API keys. Sign in as a workspace admin, open Integrations, choose REST API, then CREATE API KEY. Only admins can create keys.
2. Choose only the access it needs. Permissions are grouped by product: publishing, messaging, link in bio and webhooks. None is selected for you, so tick only what the integration needs, and set an expiry date if you like. A script that only reads analytics should not be able to delete posts. To create and schedule posts, a key needs both the write and the publish permission for posts.
3. Copy it and store it safely. The key is shown only once, so copy it right away. Keep it in a secret manager or a server environment variable, never in front-end code or a public repository.
4. Make a first request. Check the key with GET https://app.postocial.com/os/api/ping, which needs any publishing permission and returns {"status":"ok"} when the key is valid. A key with only messaging permissions can call GET https://app.postocial.com/api/v1/account instead. Then follow the API documentation to list your accounts.
5. Use one key per integration. A separate key for each integration lets you replace one without breaking the rest.

Where requests go

For example, GET https://app.postocial.com/os/api/{workspace ID}/accounts lists your connected accounts. Your workspace ID is the id that GET https://app.postocial.com/api/v1/account returns, a call that needs a key with at least one messaging permission. Send the key in an x-api-key header or as Authorization: Bearer followed by the key, but not both.

Work with the Messaging API

The Messaging API reaches the same contacts and conversations as your inbox:

• Contacts: create and update them, act on many at once, and manage their tags, notes and pipeline stage.
• Conversations: list them and read their messages, mark them read, assign them, open or close them, pause the bot, block a contact and add notes.
• Messages: send them on the contact's channel. Postocial refuses messages to blocked or opted-out contacts, and free-form messages once the reply window has closed: to restart a WhatsApp conversation, send an approved template. An idempotency key makes a retried send go out only once.
• Segments and broadcasts: manage segments, then create, approve and send broadcasts and read their recipients.
• Automations: read them and switch them on or off. Building them stays in the app.
• Channels and media: read your connected channels and upload media.

Stay within the rate limit

Each API key can make 60 requests per minute. A few habits keep you well inside that:

• Spread out bulk jobs. At the full rate, creating 300 posts takes at least five minutes.
• Keys used from the same server also share a limit of 300 requests per minute per IP address.
• Cache data that rarely changes, such as your account list, instead of fetching it before every call.
• Use webhooks instead of polling to learn when a post is published or fails.
• If you get a 429 response, wait the number of seconds in its Retry-After header, then retry.

Receive webhooks

Postocial sends signed webhooks when posts and accounts change, so your systems can react right away:

On Premium and higher plans, you can also receive messaging events. They cover contacts, conversations (including the ad a conversation started from), message delivery, automations, broadcasts, payments, store orders and bookings.

Integrations > Webhooks has three kinds of endpoint:

• Workspace webhooks: one endpoint for the publishing events above and, on Premium and higher plans, messaging events. The steps below set one up.
• Publishing: webhooks for post and account events only.
• CRM & messaging: on Premium and higher plans, endpoints for messaging events from every channel, or from one of WhatsApp, Messenger, Instagram and SMS. They retry a failed delivery up to 3 times.

To start receiving them:

1. Create an endpoint. Set up a public HTTPS endpoint on your server to receive webhook requests.
2. Add it in Postocial. Open Integrations and choose Webhooks. Under Workspace webhooks, choose CREATE ENDPOINT, give it a name and its HTTPS address, then pick the events you want. Nothing is selected for you.
3. Turn it on and test it. New endpoints start paused. Copy the signing secret when it is shown, turn the endpoint on, then send a test event and check it in the delivery history.
4. Verify every signature. Webhooks are signed with HMAC-SHA256. Check the signature against the raw request body, as the API documentation describes. Reject requests that don't match, or whose timestamp is more than 5 minutes away from your server's clock.
5. Answer fast. Return a 2xx status within 8 seconds, and do slow work in the background. Redirects are not followed and count as failed deliveries.
6. Handle repeats. A failed delivery is tried again after about 10 seconds, 1 minute, 5 minutes, 30 minutes and 2 hours, so up to 6 attempts in all. Network errors, timeouts and 408, 429 or 5xx responses are retried; other 4xx responses are final. The same event can arrive twice or out of order, so make your handler safe to run twice for the same event, and use the event time when order matters. You can resend a delivery from the delivery history.

No-code automations

Rather not write code? On Premium and higher plans, Zapier can start Zaps from Postocial's messaging events, and on every plan n8n can call the REST API with its HTTP Request node.

To set up Zapier, open Integrations, choose Zapier and generate an API key. Use it in a Zap to react to messaging events, such as a new contact, an inbound message or a sent broadcast.

Connect AI assistants with MCP

The MCP server at https://app.postocial.com/mcp lets AI assistants work in Postocial. The assistant signs in, picks one workspace, and can list accounts and draft and schedule posts. It is limited by your role.

• Claude: Settings > Connectors > Add custom connector, leaving the OAuth client ID and secret empty.
• ChatGPT: Settings > Apps & Connectors > Advanced settings, switch on Developer mode, then create a connector with OAuth, tick I trust this application and sign in.
• Claude Code: run the command below, then /mcp > Authenticate.
• Cursor: Settings > MCP, or add the URL to ~/.cursor/mcp.json.
• VS Code: add it to .vscode/mcp.json and use it in Copilot Chat agent mode.

claude mcp add --transport http postocial https://app.postocial.com/mcp

Other MCP clients work if they support remote MCP servers with OAuth sign-in: add the server URL and leave any client ID and secret empty. If an app can only send a fixed token, create a personal access token under Access Tokens in your user menu and send it in an Authorization: Bearer header. Read the full MCP guide.

Security checklist

• Keep API keys and tokens on the server side.
• Give each key the fewest permissions it needs.
• Replace the keys an admin created before they leave, and any key a departing teammate could see.
• Verify the signature on every webhook.
• Serve your webhook endpoint over HTTPS.