How to use webhooks in Postoria

Postoria webhooks send completed post publishing results to a public HTTPS endpoint you control. Use them to update an internal tracker, record published links in your CMS, or start a follow-up workflow when a publishing attempt finishes.

Webhooks are available on every plan, including Free. They work for posts created in the Postoria app and through integrations.

Before you start

  • You can configure one webhook URL per profile. It receives the selected events from all workspaces you own, including those you are not currently viewing.
  • Workspaces where you are only a team member are not included. Their owner manages the webhook settings for those workspaces.
  • Your receiver must accept HTTP POST requests at a publicly reachable HTTPS URL.
  • The URL can contain up to 2,048 characters and must not include a username, password, or URL fragment such as #section. Postoria does not follow redirects, so enter the final destination URL.
  • You do not need a Public API key to receive webhooks. Using the Public API, MCP server, or Postoria n8n integration still requires Pro or Agency.

Set up your webhook

  1. Open Settings, find Webhooks, and click Configure.
  2. Enter your receiver’s address in Webhook URL.
  3. Turn on Enable webhooks.
  4. Under Events to receive, select Post publishing succeeded, Post publishing failed, or both. At least one event must be selected while webhooks are enabled.
  5. Click Save. The dialog closes, and the Webhooks section shows Enabled and your saved URL.
  6. In the Webhooks section, find Signing secret. Its value is masked by default. Use its show or copy button to obtain the secret and configure signature verification in your receiver.

Keep the signing secret private. It lets your receiver verify that a request was signed by Postoria for your profile.

Once the receiver is ready, publish a post and check Webhook history to confirm that the event reached it. Enabling webhooks does not send events for posts that had already finished publishing.

Choose the events you need

An event describes the completed publishing attempt for a post. Postoria waits for the selected publications to finish before reporting the overall result.

EventSettingMeaning
post.succeededPost publishing succeededAll selected publications finished successfully.
post.failedPost publishing failedPublishing finished with a failure, including cases where some publications succeeded and others failed.

For example, if a post succeeds on one account and fails on another, the event is post.failed. Check the individual results before deciding what to retry; the successful publication is already live.

These events cover completed publishing attempts. They do not report media readiness, analytics updates, or inbox activity. A rejected scheduling request or an error that prevents publishing from starting does not produce a publishing-result webhook. Keep a separate check for posts that never reach a final publishing result.

Read the payload

Postoria sends JSON with Content-Type: application/json; charset=utf-8. This example shows a post with one successful result and one failed result:

{
  "id": "evt_7c7b19fd634441f3a0b460f2dc7e6812",
  "type": "post.failed",
  "occurred_at": "2026-11-15T12:00:00Z",
  "workspace_id": 42,
  "data": {
    "post_id": 1234,
    "results": [
      {
        "account_id": 101,
        "link_to_post": "https://example.com/published-post",
        "error": null
      },
      {
        "account_id": 102,
        "link_to_post": null,
        "error": "The social account needs to be reconnected."
      }
    ]
  }
}

The IDs, link, and error above are illustrative.

  • id identifies the event and stays the same across delivery attempts.
  • type is post.succeeded or post.failed.
  • occurred_at is the UTC time when Postoria recorded the completed publishing result, not the time of the latest delivery attempt.
  • workspace_id identifies the workspace. Use it to route events if your receiver serves several workspaces.
  • data.post_id is the Postoria post ID.
  • data.results contains publication results with a social account ID, a published link where available, and an error where applicable. Both link_to_post and error can be null.

The results use the same fields as the Public API’s post results. An account can appear more than once, for example when a post contains multiple Stories. Do not assume that there is exactly one result per account.

Verify the signature

Every request includes three headers:

HeaderValue
webhook-idThe event ID, matching id in the payload.
webhook-timestampUnix time in seconds for this delivery attempt.
webhook-signaturev1, followed by a Base64-encoded HMAC-SHA256 signature.

To verify a request:

  1. Read the raw request body before parsing the JSON. Parsing and serializing it again can change the bytes and invalidate the signature.

  2. Remove the whsec_ prefix from your signing secret and Base64-decode the remaining value to obtain the signing key.

  3. Join the webhook-id header, the webhook-timestamp header, and the raw body in that order, with a literal period between each part:

    webhook-id.webhook-timestamp.raw-request-body
  4. Compute HMAC-SHA256 over the UTF-8 bytes of that string using the decoded signing key, then Base64-encode the digest.

  5. Compare your result with the value after v1, in webhook-signature, using a constant-time comparison.

  6. Check that the signed timestamp is within your receiver’s allowed clock tolerance to limit replay of old requests. Use the header timestamp for this check, because retries can arrive long after occurred_at.

Reject requests with missing or invalid signature headers before acting on their contents. Use webhook-id to recognize events your receiver has already processed.

Respond promptly and handle retries

Return an HTTP 2xx response within 10 seconds to acknowledge a delivery. A practical receiver verifies the request, stores the event and its ID durably, and then returns the response. Longer follow-up work can run separately after that acknowledgement.

Postoria queues the initial delivery as soon as the publishing result is recorded. Non-2xx responses, timeouts, and connection failures trigger automatic retries. Redirect responses also count as failed delivery attempts.

Retry targets are 5, 15, and 30 minutes, then 1, 3, 6, 12, and 24 hours after the first attempt. These are offsets from the first attempt, not delays after the previous attempt. Actual delivery can occur later if processing is delayed. The schedule provides up to nine attempts, including the initial attempt.

The event ID and JSON body stay the same across retries. Each attempt receives a new send timestamp and a signature calculated for that attempt. Duplicate deliveries are possible, so make repeated handling of the same event safe. Do not rely on different events arriving in publishing order.

Retrying a webhook only retries delivery of the result. It does not publish the post again.

Inspect delivery history

Open Settings → Webhooks → Webhook history, or go directly to Webhook history.

The history covers your owned workspaces and is retained for 30 days. Each row shows the event, post ID, workspace ID, delivery status, attempt count, and last HTTP status. Expand a row to see its message ID, attempt times, delivery time, error if present, and JSON body.

Delivery statusMeaning
WaitingThe message is waiting for its initial delivery or a retry.
SendingA delivery attempt is in progress.
DeliveredYour receiver returned a successful HTTP response.
FailedDelivery attempts ended without a successful HTTP response.

Delivery status and publishing outcome are different. A post.failed event can be Delivered: publishing had a failure, but your receiver successfully received that information.

Reload the page to see the latest delivery statuses, and use Load more to view older messages. If loading fails, Try again retries loading the history. These actions do not resend webhooks.

Change the URL or disable webhooks

In Settings → Webhooks, click Configure, update the URL or turn off Enable webhooks, then click Save. The change affects newly created events.

Closing the configuration dialog without clicking Save discards your edits.

When webhooks are disabled, the Webhooks section shows Disabled and hides the saved URL and signing secret. Click Configure to edit the URL or enable webhooks again.

Events already captured retain their original destination URL and can continue retrying. Disabling webhooks does not cancel those pending deliveries, and changing the URL does not redirect them to the new address.

Troubleshooting

  • The settings will not save: check that the URL uses HTTPS, is public, has no embedded credentials or fragment, and fits the length limit. Select at least one event when enabling webhooks.
  • No event appears: check that webhooks were enabled before publishing finished, the corresponding event was selected, and you own the workspace. An error before publishing starts is outside these events.
  • Delivery keeps failing: inspect the last HTTP status and error in Webhook history. Check that the endpoint is reachable directly, has a valid HTTPS certificate, accepts POST, and returns 2xx within 10 seconds.
  • Signature verification fails: use the raw body, Base64-decode the secret after removing whsec_, and include the exact header values and separating periods in the signed string.
  • The same event arrives again: deduplicate by event ID rather than post ID. A later publishing attempt for the same post can produce a different event.