Skip to content

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.

Post events
EventDescription
post.scheduledA post was accepted and scheduled for future publication.
post.publishedEvery platform target published successfully without warnings.
post.partialAt least one platform failed or returned a warning.
post.failedEvery platform target failed to publish.

Source contract parity; decision criteria based on per-platform results.

Connected account events
EventDescription
account.reauthorization_requiredStored authorization stopped working and the account must be reconnected.
account.disconnectedThe account was intentionally disconnected.

Source contract parity.

Webhook headers
HeaderDescription
X-PostPeer-Event-IdUnique event ID
X-PostPeer-Event-TypeEvent type, such as post.published
X-PostPeer-TimestampUnix timestamp in seconds
X-PostPeer-SignatureHMAC-SHA256 signature prefixed with sha256=
Content-Typeapplication/json
User-AgentPostPeer-Webhooks/1.0

Exact source header names preserved.

Top-level fields
FieldTypeDescription
versionstringWebhook payload version
idstringUnique event ID; use it to detect duplicate deliveries
typestringSubscription event type
createdAtstringISO 8601 event creation time
projectIdstringProject that owns the event resource
profileIdstring or nullProfile selected by the subscription, if any
dataobjectEvent-specific post or account data

Types and nullability preserved.

data.account fields
FieldTypeDescription
idstringConnected-account ID
platformstringSocial platform
platformUserIdstring or nullPlatform-native account or channel ID
usernamestring or nullPlatform username
displayNamestring or nullPlatform display name
statusstringreconnect_required or disconnected
reasonstring or nullAuthorization failure reason when reconnection is required

Types and nullability preserved.

data.post fields
FieldTypeDescription
idstringPost ID; matches the postId returned when creating a post
statusstringCurrent overall post status
contentstringPost text
scheduledForstring or nullScheduled publication time in ISO 8601 format
publishedAtstring or nullEarliest successful platform publication time
mediaItemsarrayMedia attached to the post
linksobjectDashboard and API URLs for the post

Types and nullability preserved.

data.platforms fields
FieldTypeDescription
platformstringSocial platform
integrationIdstringConnected account integration ID
profileIdstring or nullProfile assigned to the integration
statusstringStatus for this platform
platformPostIdstring or nullPost ID returned by the social platform
platformPostUrlstring or nullPublished post URL
publishedAtstring or nullPlatform publication time
errorMessagestring or nullFailure reason
warningMessagestring or nullNon-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.

Connected account payload example
{
	"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 request 1
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"
    }
  }'
Post webhook payload example
{
	"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
			}
		]
	}
}