Webhooks

Webhooks send a signed HTTP POST to your URL when something happens in PostEverywhere, such as a post publishing or failing. You create them through the API or by asking a connected AI agent.

Steps#

1. Create a key with the Write permission on Developers › API Keys.
2. Create the webhook:

POST https://app.posteverywhere.ai/api/v1/webhooks
{
  "url": "https://example.com/hooks/posteverywhere",
  "events": ["post.published", "post.failed"],
  "name": "My server"
}

3. Save the secret from the response now. It starts with whsec_ and is shown only once.
4. Send a test: POST /v1/webhooks/{id}/test. The test call carries the header X-PostEverywhere-Test: true.

With an AI agent, ask it to create a webhook. The tools are list_webhooks, create_webhook, get_webhook, update_webhook, delete_webhook and test_webhook. They are not available in the ChatGPT app.

Events#

Posts: post.scheduled, post.publishing, post.published, post.failed, post.partially_failed, post.warning, post.updated, post.deleted.

Approvals: post.approval_requested, post.approved, post.changes_requested.

Accounts: account.connected, account.disconnected, account.reconnect_needed.

Media: media.uploaded, media.deleted.

Verify the signature#

Every call has these headers:

• X-PostEverywhere-Event: the event name
• X-PostEverywhere-Event-Id: unique id, use it to ignore duplicates
• X-PostEverywhere-Timestamp: Unix seconds
• X-PostEverywhere-Signature: sha256= followed by the HMAC-SHA256 of the raw request body, using your secret
• X-PostEverywhere-Delivery-Id and X-PostEverywhere-Attempt

Compute HMAC-SHA256 over the raw body with the secret and compare it to the header.

The body is:

{
  "event": "post.published",
  "event_id": "...",
  "created_at": "...",
  "organization_id": "...",
  "data": { }
}

Retries#

Answer with any 2xx status within 10 seconds. If we get anything else, we try again after 30 seconds, 2 minutes, 10 minutes, 1 hour and 6 hours. After 6 attempts the delivery is marked dead. After 20 failures in a row the webhook is switched off and the team owner is told.

Details#

• The URL must be a public https address.
• events must list at least one valid event. An unknown event name returns 400 invalid_event_type with the valid list.