Webhook signature verification
Webhook signature verification lets a receiving service trust asynchronous notifications about publishing outcomes and connected-account health. This guide covers the event catalog, delivery and retry behavior, subscription creation, post identification, signature checking, and the payload fields needed to update records safely.
Event catalog and decision criteria
Notifications fall into two groups. Publishing notifications use post.scheduled, post.published, post.partial and post.failed. Account notifications use account.reauthorization_required and account.disconnected. Acceptance of a future-dated item triggers post.scheduled. Completion later produces exactly one closing notice, chosen from the three outcome names. Items sent straight away skip the scheduling notice and go directly to a closing notice. Closing notices bundle every destination outcome inside data.platforms; individual destination notices are not issued. A subscription scoped by profileId narrows that bundle to destinations belonging to that profile. Turning onlyScheduledPosts on limits closing notices to items that had originally been queued for later. On the account side, account.reauthorization_required signals broken stored credentials needing a fresh link, whereas account.disconnected signals a deliberate unlink. For YouTube, a rejected refresh token discovered during an operation raises the reauthorization notice; brief network or provider hiccups do not raise it.
Delivery, retry, and idempotency model
Delivery arrives as an HTTP POST aimed at the registered URL. Any status in the 200 range counts as receipt, so acknowledge quickly once the notice is safely stored and defer heavier processing to queued work. When acknowledgement does not arrive, the sender waits ten seconds, then tries again with growing delays, stopping after three attempts in total. Repetition is therefore expected behavior. Guard against it by recording the envelope identifier and discarding anything already seen; that identifier serves as the webhook idempotency key handling mechanism. Handling a publishing notice means checking authenticity from the untouched body, dropping repeats, locating the local row through data.post.id, saving both the headline status and each destination status, and finally answering with a 2xx code. Build checks for slow or missing acknowledgements, exhausted retries, repeats, bad signatures, stale timestamps used for replay, and destination-level errorMessage or warningMessage entries.
Create webhook subscription contract
Registration is done once per set of wanted event names, following the sample titled Create a webhook subscription. Send POST to {{API_BASE_URL}}/v1/notifications/ with the trailing slash preserved, with x-access-key carrying the credential, Content-Type set to application/json, channel equal to webhook, eventTypes listing the chosen names, and webhook.url pointing at the receiver. The creation answer carries the shared secret at notification.webhook.secret. Keep that value in secure storage; later listing calls show only a masked form. Further subscription options live in the notification API reference. Match the method, path, header spelling and field names exactly in client code.
Identify the post and update workflow
At creation time, keep the postId returned synchronously alongside the local record. Later notices repeat that same identifier inside data.post.id, which is the lookup key. Apply data.post.status to that row. No separate identifier invented for webhook purposes is needed. This bridge connects the immediate creation answer with scheduled post webhook events arriving afterwards. Also save every data.platforms entry, preserving platformPostId, errorMessage and warningMessage for later support, reporting or user-facing display.
Signature verification with Node.js and Python examples
Each delivery carries the headers shown in the table titled Webhook headers. Checking authenticity starts with the untouched body bytes, because parsing first would change the bytes and break the check. Build the signed string by concatenating the timestamp header, a dot, and those raw bytes. Apply HMAC SHA256 using the shared secret, render the result as hex, add the sha256= prefix, then compare against the supplied signature using a timing-safe method. Timestamps far from the current clock should be refused, limiting replay; five minutes is suggested as a tolerance. In the Node.js and Express sample, the raw-body parser must be attached to the route ahead of any JSON parser, missing inputs yield 400, stale or mismatched inputs yield 401, and success yields 200. The Python and FastAPI sample mirrors those outcomes with compare_digest. In both samples, replace the commented persistence line with a real database call before use.
Payload field maps and worked payload examples
Both families share envelope shape, headers, signing and retry behavior. Publishing notices nest post plus platforms under data. Account notices nest account under data and omit post and platforms. Samples titled Post webhook payload example and Connected account payload example illustrate each shape. Reference tables below give types and nullability for envelope fields, account fields, post fields and platform fields. Remember scheduledFor may be null and otherwise holds an ISO 8601 moment; publishedAt marks the earliest successful destination time. Media entries always carry type, url, thumbnail, filename, size and mimeType, and may additionally carry dimensions, duration, codecs, bitrate and probe status for video or normalized media. For destinations, platformPostId, platformPostUrl, publishedAt, errorMessage and warningMessage may each be null; a populated warningMessage denotes a non-fatal warning and can accompany post.partial.
| Event | Description |
|---|---|
| post.scheduled | A post was accepted and scheduled for future publication. |
| post.published | Every platform target published successfully without warnings. |
| post.partial | At least one platform failed or returned a warning. |
| post.failed | Every platform target failed to publish. |
Source contract parity; decision criteria based on per-platform results.
| Event | Description |
|---|---|
| account.reauthorization_required | Stored authorization stopped working and the account must be reconnected. |
| account.disconnected | The account was intentionally disconnected. |
Source contract parity.
| Header | Description |
|---|---|
| X-PostPeer-Event-Id | Unique event ID |
| X-PostPeer-Event-Type | Event type, such as post.published |
| X-PostPeer-Timestamp | Unix timestamp in seconds |
| X-PostPeer-Signature | HMAC-SHA256 signature prefixed with sha256= |
| Content-Type | application/json |
| User-Agent | PostPeer-Webhooks/1.0 |
Exact source header names preserved.
| Field | Type | Description |
|---|---|---|
| version | string | Webhook payload version |
| id | string | Unique event ID; use it to detect duplicate deliveries |
| type | string | Subscription event type |
| createdAt | string | ISO 8601 event creation time |
| projectId | string | Project that owns the event resource |
| profileId | string or null | Profile selected by the subscription, if any |
| data | object | Event-specific post or account data |
Types and nullability preserved.
| Field | Type | Description |
|---|---|---|
| id | string | Connected-account ID |
| platform | string | Social platform |
| platformUserId | string or null | Platform-native account or channel ID |
| username | string or null | Platform username |
| displayName | string or null | Platform display name |
| status | string | reconnect_required or disconnected |
| reason | string or null | Authorization failure reason when reconnection is required |
Types and nullability preserved.
| Field | Type | Description |
|---|---|---|
| id | string | Post ID; matches the postId returned when creating a post |
| status | string | Current overall post status |
| content | string | Post text |
| scheduledFor | string or null | Scheduled publication time in ISO 8601 format |
| publishedAt | string or null | Earliest successful platform publication time |
| mediaItems | array | Media attached to the post |
| links | object | Dashboard and API URLs for the post |
Types and nullability preserved.
| Field | Type | Description |
|---|---|---|
| platform | string | Social platform |
| integrationId | string | Connected account integration ID |
| profileId | string or null | Profile assigned to the integration |
| status | string | Status for this platform |
| platformPostId | string or null | Post ID returned by the social platform |
| platformPostUrl | string or null | Published post URL |
| publishedAt | string or null | Platform publication time |
| errorMessage | string or null | Failure reason |
| warningMessage | string or null | Non-fatal warning |
Types and nullability preserved.
Frequently asked questions
How do I verify a webhook signature?
Read the raw body, build timestamp plus a period plus the raw body, compute HMAC-SHA256 with the signing secret, prefix the hex digest with sha256=, compare in constant time, and reject timestamps older than your tolerance, commonly five minutes.
How should duplicate webhook deliveries be handled?
Store the top-level event id as an idempotency key, check it before processing, and skip any event already processed because deliveries may be retried up to three times.
Which final post event should I expect?
Use post.published when every target succeeds without warnings, post.partial when at least one target fails or warns, and post.failed when every target fails. Inspect data.platforms for platformPostId, errorMessage, and warningMessage.
{
"version": "2026-06-01",
"id": "evt_123",
"type": "account.reauthorization_required",
"createdAt": "2026-06-06T12:00:00.000Z",
"projectId": "project_123",
"profileId": null,
"data": {
"account": {
"id": "account_123",
"platform": "youtube",
"platformUserId": "UC123",
"username": "@example",
"displayName": "Example",
"status": "reconnect_required",
"reason": "refresh_rejected"
}
}
}curl -X POST "{{API_BASE_URL}}/v1/notifications/" \
-H "x-access-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"channel": "webhook",
"eventTypes": [
"post.scheduled",
"post.published",
"post.partial",
"post.failed",
"account.reauthorization_required",
"account.disconnected"
],
"webhook": {
"url": "https://example.com/webhooks/postpeer"
}
}'{
"version": "2026-06-01",
"id": "evt_123",
"type": "post.published",
"createdAt": "2026-06-06T12:00:00.000Z",
"projectId": "project_123",
"profileId": null,
"data": {
"post": {
"id": "post_123",
"status": "published",
"content": "A short example update.",
"scheduledFor": null,
"publishedAt": "2026-06-06T12:00:00.000Z",
"mediaItems": [],
"links": {
"postpeer": "https://apisocials.com/dashboard/posts?post=post_123",
"api": "{{API_BASE_URL}}/v1/posts/post_123"
}
},
"platforms": [
{
"platform": "twitter",
"integrationId": "integration_123",
"profileId": null,
"status": "published",
"platformPostId": "tweet_123",
"platformPostUrl": "https://x.com/user/status/tweet_123",
"publishedAt": "2026-06-06T12:00:00.000Z",
"errorMessage": null,
"warningMessage": null
}
]
}
}