SDK Webhooks - Social media studio

Embedded webhooks notify your server when activity occurs for any end user in your partner project. Each payload identifies the affected end user so you can route it back to the correct customer.

Create a subscription

Webhook endpoints must use HTTPS and must be publicly reachable.

const webhook = await soMe.webhooks.create({
  url: "https://app.example.com/webhooks/so-me",
  events: ["post.published", "post.failed"],
});

// Save this value immediately; it is returned only on creation.
await secrets.store("some-webhook-secret", webhook.secret!);

Omit events, or pass an empty array, to receive every recognized event that occurs for your embedded end users.

const subscriptions = await soMe.webhooks.list();
await soMe.webhooks.remove(webhook.id);

Useful events for an embedded publishing integration include:

Event	Meaning
`social.account_connected`	A social account was connected
`social.account_disconnected`	A social account was disconnected
`post.scheduled`	A post entered the publishing queue
`post.published`	The social platform accepted the post
`post.failed`	Publishing failed

Verify the signature

Social media studio signs the exact raw HTTP request body with HMAC-SHA256. Read the body as text or bytes and verify it before parsing JSON.

import {
  verifyWebhookSignature,
  type EmbeddedWebhookEvent,
} from "@social-media-scheduler/sdk";

export async function POST(request: Request) {
  const rawBody = await request.text();
  const signature = request.headers.get("x-webhook-signature") ?? "";

  if (
    !verifyWebhookSignature(
      rawBody,
      signature,
      process.env.SOME_WEBHOOK_SECRET!,
    )
  ) {
    return new Response("Invalid signature", { status: 401 });
  }

  const event = JSON.parse(rawBody) as EmbeddedWebhookEvent;
  await handleEvent(event);
  return new Response(null, { status: 204 });
}

The signature may be sent as a hexadecimal digest or with a v1= prefix; the SDK accepts both forms.

Payload shape

{
  "id": "delivery_uuid",
  "event": "post.published",
  "createdAt": "2026-08-20T10:00:04.000Z",
  "endUser": {
    "id": "end_user_uuid",
    "externalId": "customer_123"
  },
  "data": {
    "postId": "post_uuid",
    "platform": "THREADS"
  }
}

Delivery requests also include:

Header	Description
`X-Webhook-Signature`	HMAC-SHA256 signature of the raw body
`X-Webhook-Event`	Event name
`X-Webhook-Delivery-Id`	Stable delivery identifier

Delivery behavior

Return a 2xx response as soon as the event is durably accepted.
Process events asynchronously when work may take more than a few seconds.
Deduplicate deliveries using the payload id or X-Webhook-Delivery-Id.
Non-2xx responses, network failures, and timeouts are retried with exponential backoff.
Repeatedly failing subscriptions are automatically disabled.

Webhook delivery is at least once, so handlers must be idempotent.

​Create a subscription

​Verify the signature

​Payload shape

​Delivery behavior

Create a subscription

Verify the signature

Payload shape

Delivery behavior