API & Webhooks#

The Automation API lets you create and manage campaigns, read your connected groups and targeting presets, and push conversion events from your own tools. Webhooks notify your server when posts publish, fail, or when campaigns finish.

Availability: Pro AI only. Generate a scoped API key from Settings → API & Webhooks in the dashboard.

Base URL: https://app.pilotposter.com/api/v1

Authentication#

Every request needs an Authorization header:

code

Authorization: Bearer pp_live_xxxxxxxxxxxxxxxx

Create a key from Settings → API & Webhooks. Choose only the scopes your integration needs. Keys are shown once at creation, stored hashed on our side, and can be revoked at any time.

Scopes#

Scope	What it allows
`campaigns:read`	List and read campaigns, groups, and targeting presets
`campaigns:write`	Create, pause, and cancel campaigns
`outcomes:write`	Submit conversion and lead events from your own systems

Rate limits#

Each API key is limited to 60 requests per minute. Requests over the limit return 429 Too Many Requests. Back off and retry.

Endpoints#

Method	Path	Scope	Description
GET	`/campaigns`	`campaigns:read`	List your campaigns, optionally filtered by status
POST	`/campaigns`	`campaigns:write`	Create a new campaign, scheduled or paused as a draft
GET	`/campaigns/:id`	`campaigns:read`	Get a single campaign's status and per-group results
POST	`/campaigns/:id/pause`	`campaigns:write`	Pause a running or scheduled campaign
POST	`/campaigns/:id/cancel`	`campaigns:write`	Cancel a campaign so it is never processed again
GET	`/groups`	`campaigns:read`	List the Facebook groups you have connected
GET	`/targeting-presets`	`campaigns:read`	List your saved targeting presets
POST	`/outcomes`	`outcomes:write`	Submit a conversion or lead event from your own systems (e.g. a CRM)

Create a campaign#

bash

curl https://app.pilotposter.com/api/v1/campaigns \
  -H "Authorization: Bearer pp_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "New listing just hit the market!",
    "scheduledTime": "2026-08-01T15:00:00Z",
    "groupList": [{ "id": "123456789", "name": "Local Buy & Sell" }],
    "sleepBetweenPosts": 10
  }'

[!tip] The Chrome extension must be connected when a scheduled campaign is due to run. If the extension is offline, posts wait until it reconnects. Subscribe to the extension.offline webhook to get notified.

Webhooks#

Point PilotPoster at your own HTTPS endpoint from Settings → API & Webhooks. You receive a signed request for every event you subscribe to.

Events#

Event	When it fires
`post.published`	A post was successfully published to a specific group
`post.failed`	A post failed to publish to a specific group
`campaign.completed`	A campaign finished processing every targeted group
`campaign.failed`	A campaign could not proceed and was marked failed
`outcome.recorded`	A click or conversion was recorded against a tracked link
`extension.offline`	Your Chrome extension has gone offline and posts may be delayed
`report.ready`	A scheduled or requested report has finished generating
`approval.changed`	An Auto AI post moved through the review queue (approved, edited, or skipped)

Verify the signature#

Every webhook request includes an X-PilotPoster-Signature header: an HMAC-SHA256 of the raw request body using your account's signing secret. Recompute and compare before trusting the payload.

javascript

const crypto = require("crypto");

function verifySignature(rawBody, signatureHeader, secret) {
  const expected = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signatureHeader)
  );
}

Retries and replay#

Failed webhook deliveries retry up to 4 times with backoff. Every attempt, successful or not, appears in your delivery log. You can replay any past delivery manually from Settings → API & Webhooks. Rotate your signing secret at any time if you suspect it was exposed.

What's next?#

Create Campaign: build campaigns from the dashboard
Logs and Troubleshooting: confirm posts went out
Billing: upgrade to Pro AI to unlock the API
Developers page on pilotposter.com: overview and FAQ

Need help? Email support@pilotposter.com.