> ## Documentation Index
> Fetch the complete documentation index at: https://docs.postonce.to/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Get a signed event when an API post publishes, partly publishes, or fails, instead of polling.

Register an HTTPS URL and PostOnce sends it an event when a post you created through the API finishes. Every request is signed, failed deliveries are retried for about 21 hours, and each event is logged so you can see what your endpoint returned.

## Create a webhook

```bash theme={null}
curl -s \
  -H "Authorization: Bearer po_live_xxxxx_xxxxx" \
  -H "Content-Type: application/json" \
  -X POST https://postonce.to/api/public/v1/webhooks \
  -d '{ "url": "https://example.com/postonce/webhook" }'
```

The response includes `secret` (`whsec_...`). Store it now: it is never shown again. To rotate it, create a new webhook and delete the old one.

* Up to 5 webhooks per account. Each receives every event.
* A webhook gets events for posts created after it was registered.
* The URL must be HTTPS on a public host. Redirects are not followed.

## Events

| Event | Sent when |
| - | - |
| `post.published` | Every destination published. |
| `post.partially_published` | At least one destination published and the others failed. |
| `post.failed` | Every destination failed. |
| `ping` | You call `POST /v1/webhooks/{id}/test`. |

An event is sent once every destination of the post has finished, so a post with one destination still publishing sends nothing yet. Each outcome is sent once. If you retry a failed destination with `POST /v1/posts/{id}/targets/{targetId}/retry`, you get a new event for the retry's outcome, even if it is the same type as before. A scheduled post that PostOnce retries automatically sends one event, after its last attempt.

The body's `data` is the same post object `GET /v1/posts/{id}` returns. Failed destinations also carry `action_required` when the account owner has to do something before posting can work, such as reconnecting the account or verifying an email on the platform. Otherwise it is `null`.

```json theme={null}
{
  "id": "6f1c2a9e-1b9f-4a51-9d1e-3a0c2f8b7d10",
  "type": "post.partially_published",
  "created_at": "2026-11-16T15:04:05.000Z",
  "data": {
    "id": "8a6f3f1c-2f1f-4c95-9cf5-e0d8bb5a41e2",
    "status": "partial",
    "external_id": "launch-42",
    "content": "Launch day",
    "targets": [
      {
        "target_post_id": "b1d0...",
        "platform": "instagram",
        "status": "published",
        "platform_post_url": "https://www.instagram.com/reel/...",
        "error": null,
        "action_required": null
      },
      {
        "target_post_id": "c2e1...",
        "platform": "youtube",
        "status": "failed",
        "error": "Reconnect your YouTube account.",
        "action_required": {
          "code": "reconnect_account",
          "message": "Reconnect this account, then retry the post.",
          "action_url": null
        }
      }
    ]
  }
}
```

## Headers

| Header | Value |
| - | - |
| `PostOnce-Signature` | `t=<unix seconds>,v1=<hex HMAC-SHA256>` |
| `PostOnce-Event-Id` | Same as the body's `id`. It stays the same across retries, so use it to ignore duplicates. |
| `PostOnce-Event-Type` | Same as the body's `type`. |

## Verify the signature

Compute HMAC-SHA256 with your secret over `<t>.<raw request body>` and compare it with `v1`. Reject requests whose `t` is more than 5 minutes old. Use the raw body: parsing and re-serialising JSON changes the bytes.

```js theme={null}
import crypto from "node:crypto";

export function verifyPostOnceWebhook(rawBody, header, secret) {
  const parts = Object.fromEntries(
    header.split(",").map((part) => part.split("=", 2)),
  );
  const timestamp = Number(parts.t);
  if (!timestamp || Math.abs(Date.now() / 1000 - timestamp) > 300) return false;
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");
  return (
    typeof parts.v1 === "string" &&
    parts.v1.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected))
  );
}
```

## Respond and retries

Return any `2xx` within 10 seconds. Do slow work after you respond.

Anything else (an error status, a redirect, a timeout, or a connection error) is retried after about 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours and 12 hours: 7 attempts in all. Events can arrive more than once and out of order, so check `PostOnce-Event-Id` and the post's `status`.

## Test and debug

* `POST /v1/webhooks/{id}/test` sends a signed `ping` right away and returns the delivery, including the status code your endpoint returned.
* `GET /v1/webhooks/{id}/deliveries` lists the last 50 events with their status, attempts, last status code, last error and next retry.
* `GET /v1/posts/{id}` always has the current state if you missed an event.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.