Webhooks

Delivery is asynchronous, so a 202 from the publish endpoint tells you the post was accepted, not that it is live. Webhooks are how you find out what actually happened without polling: FoPost POSTs a signed JSON event to your endpoint when a post is scheduled or publishes, a delivery fails, an account connects or its credentials degrade, something new lands in the inbox, or an automation runs.

These endpoints need the webhooks scope, and work from the API, the SDKs, or the CLI.

POST /v1/webhooks

curl -X POST https://api.fopost.com/v1/webhooks \
  -H "X-API-Key: $FOPOST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workspaceId": "7d2b8c11-4e5a-4a8f-b0d9-3c5e6f7a8b90",
    "name": "Production",
    "url": "https://yourbrand.com/hooks/fopost",
    "events": ["post.published", "post.partially_failed", "delivery.failed"],
    "headers": { "Authorization": "Bearer your-own-token" }
  }'

workspaceId, url, and at least one event are required; the names are on the events page. Use an HTTPS URL your server exposes publicly; deliveries come from the open internet.

Optional fields:

Field	What it does
`name`	A label for the endpoint, up to 120 characters. Shown in the dashboard, never sent
`secret`	Your own signing secret, 16 to 255 characters. Omit it and one is generated
`headers`	Up to 10 custom headers sent with every delivery, such as an `Authorization` header your endpoint checks. Names use letters, digits and hyphens. The signing headers, `Content-Type` and `Host` cannot be set here. Values are write-only: responses carry `headerNames`, never the values

The response carries the webhook's signing secret. It is returned only on creation and on the update that rotates it, and is never shown by a GET. It is what you verify the signature with.

Manage

Endpoint	What it does
`GET /v1/webhooks`	List your subscriptions, with `lastTriggeredAt` and `failureCount`. Spans every workspace you belong to
`PUT /v1/webhooks/{id}`	Change the name, URL, events, headers, or `active`. `headers` replaces the set; give an existing header a `null` value to keep what is stored. Pass `secret` to rotate it: the new value comes back once in that response. Setting `active: true` also resets the failure count
`POST /v1/webhooks/{id}/test`	Send a test event to this endpoint. See test deliveries for how it behaves
`DELETE /v1/webhooks/{id}`	Delete it

Workspace viewers can list webhooks but not create, change, or delete them.

The shape of a delivery

Every event arrives as a POST with a three-key JSON body:

{
  "event": "delivery.published",
  "data": { "postId": "…", "accountId": "…", "platform": "linkedin", "externalUrl": "…" },
  "timestamp": "2026-09-01T09:00:12.000Z"
}

There is no id inside the body: the delivery id travels in the X-FoPost-Delivery header, which is also what you deduplicate on. The full per-event data shapes are on the events page.

In this section

EventsEvery event that can fire, when it fires, and its payload.Verifying SignaturesProve a delivery came from FoPost before acting on it.Retries and FailuresTimeouts, retry backoff, auto-disable, and test deliveries.

PublishingCreate a post, target accounts, publish it, and read the per-account result.AutomationsTrigger and pipeline workflows that publish without a human in the loop.

Manage

The shape of a delivery

In this section

Next

On this page