Payload Format & Verification - Social media studio

Every webhook Social media studio delivers follows the same envelope and signing scheme. This page shows the exact request shape, how to verify the signature, and what the data block looks like for common events.

Request Format

Headers

Every delivery includes these headers:

Header	Description
`Content-Type`	`application/json`
`X-Webhook-Event`	The event name, e.g. `post.published`
`X-Webhook-Delivery-Id`	UUID of the delivery log row, useful for deduping retries
`X-Webhook-Signature`	HMAC-SHA256 of the raw request body, hex-encoded, signed with your endpoint’s secret

Envelope

Unless you configure a custom payloadTemplate, the body is a JSON object with four fields:

{
  "event": "post.published",
  "category": "post",
  "timestamp": "2026-04-22T14:30:00.000Z",
  "data": {
    "postId": "01J...",
    "platform": "instagram",
    "userId": "usr_..."
  }
}

event — The exact event name (matches X-Webhook-Event)
category — The category the event belongs to (e.g. post, inbox, subscription)
timestamp — ISO-8601 timestamp of when the event was dispatched
data — The event-specific payload (see examples below)

Retries reuse the same X-Webhook-Delivery-Id. Use it as an idempotency key so a retried delivery doesn’t re-process an already-handled event.

Signature Verification

Every request body is signed with your endpoint’s secret using HMAC-SHA256. Verify it on every request to confirm the delivery genuinely came from Social media studio.

Always verify using the raw request body before it’s parsed as JSON — re-serializing the parsed object will change whitespace and invalidate the signature.

import express from "express";
import crypto from "crypto";

const app = express();
const WEBHOOK_SECRET = process.env.SOMESTUDIO_WEBHOOK_SECRET;

app.post(
  "/webhook",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const signature = req.header("X-Webhook-Signature");
    const expected = crypto
      .createHmac("sha256", WEBHOOK_SECRET)
      .update(req.body)
      .digest("hex");

    if (
      !signature ||
      !crypto.timingSafeEqual(
        Buffer.from(signature, "hex"),
        Buffer.from(expected, "hex"),
      )
    ) {
      return res.status(401).send("Invalid signature");
    }

    const payload = JSON.parse(req.body.toString("utf8"));
    console.log(payload.event, payload.data);

    res.status(200).send("ok");
  },
);

app.listen(3000);

import hmac
import hashlib
import os
from flask import Flask, request, abort

app = Flask(__name__)
WEBHOOK_SECRET = os.environ["SOMESTUDIO_WEBHOOK_SECRET"]

@app.post("/webhook")
def webhook():
    signature = request.headers.get("X-Webhook-Signature", "")
    expected = hmac.new(
        WEBHOOK_SECRET.encode(),
        request.get_data(),
        hashlib.sha256,
    ).hexdigest()

    if not hmac.compare_digest(signature, expected):
        abort(401)

    payload = request.get_json()
    print(payload["event"], payload["data"])
    return "ok", 200

<?php
$secret    = getenv('SOMESTUDIO_WEBHOOK_SECRET');
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
$body      = file_get_contents('php://input');
$expected  = hash_hmac('sha256', $body, $secret);

if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit('Invalid signature');
}

$payload = json_decode($body, true);
error_log($payload['event']);

http_response_code(200);
echo 'ok';

package main

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
    "io"
    "net/http"
    "os"
)

var secret = []byte(os.Getenv("SOMESTUDIO_WEBHOOK_SECRET"))

func webhook(w http.ResponseWriter, r *http.Request) {
    body, _ := io.ReadAll(r.Body)
    defer r.Body.Close()

    mac := hmac.New(sha256.New, secret)
    mac.Write(body)
    expected := hex.EncodeToString(mac.Sum(nil))

    if !hmac.Equal([]byte(expected), []byte(r.Header.Get("X-Webhook-Signature"))) {
        http.Error(w, "Invalid signature", http.StatusUnauthorized)
        return
    }

    w.WriteHeader(http.StatusOK)
    w.Write([]byte("ok"))
}

func main() {
    http.HandleFunc("/webhook", webhook)
    http.ListenAndServe(":3000", nil)
}

Example Payloads

The data block shape depends on the event. Here are representative examples from commonly-used categories.

Post

{
  "event": "post.published",
  "category": "post",
  "timestamp": "2026-04-22T14:30:00.000Z",
  "data": {
    "postId": "01JABC123...",
    "platform": "instagram",
    "userId": "usr_abc123"
  }
}

{
  "event": "post.failed",
  "category": "post",
  "timestamp": "2026-04-22T14:31:00.000Z",
  "data": {
    "postId": "01JABC123...",
    "platform": "twitter",
    "failureReason": "Social account session has expired"
  }
}

Approval

{
  "event": "post.approval.approved",
  "category": "approval",
  "timestamp": "2026-04-22T14:32:00.000Z",
  "data": {
    "postId": "01JABC123...",
    "userId": "usr_abc123",
    "reviewerId": "mem_xyz789"
  }
}

Inbox

{
  "event": "inbox.message_received",
  "category": "inbox",
  "timestamp": "2026-04-22T14:33:00.000Z",
  "data": {
    "threadId": "thr_abc",
    "messageId": "msg_xyz",
    "platform": "instagram",
    "fromUser": { "id": "ig_456", "name": "Jane Doe" }
  }
}

{
  "event": "whatsapp.message_sent",
  "category": "whatsapp",
  "timestamp": "2026-04-22T14:33:30.000Z",
  "data": {
    "accountId": "15551234567",
    "to": "+15557654321",
    "templateName": "order_update",
    "messageId": "wamid.HBgM..."
  }
}

{
  "event": "whatsapp.template_created",
  "category": "whatsapp",
  "timestamp": "2026-04-22T14:33:45.000Z",
  "data": {
    "accountId": "15551234567",
    "name": "order_update",
    "language": "en_US",
    "category": "UTILITY"
  }
}

{
  "event": "account.token_expired",
  "category": "account",
  "timestamp": "2026-04-22T14:34:00.000Z",
  "data": {
    "accountId": "acc_123",
    "platform": "facebook",
    "postId": "01JABC123..."
  }
}

Subscription

The newPlanName field contains the internal plan identifier, such as scale for Advanced.

{
  "event": "subscription.upgraded",
  "category": "subscription",
  "timestamp": "2026-04-22T14:35:00.000Z",
  "data": {
    "subscriptionId": "lsq_sub_123",
    "newPlanId": "pln_scale",
    "newPlanName": "scale"
  }
}

AI

{
  "event": "ai.image_generated",
  "category": "ai",
  "timestamp": "2026-04-22T14:36:00.000Z",
  "data": {
    "imageId": "img_abc",
    "userId": "usr_xyz",
    "prompt": "A sunset over the mountains",
    "url": "https://cdn.so-me.studio/..."
  }
}

Knowledge Hub

{
  "event": "knowledge.created",
  "category": "knowledge",
  "timestamp": "2026-04-22T14:36:30.000Z",
  "data": {
    "id": "kn_abc123",
    "title": "Brand voice guide",
    "sourceType": "pdf",
    "isActive": true
  }
}

Analytics

{
  "event": "analytics.report_generated",
  "category": "analytics",
  "timestamp": "2026-04-22T14:00:00.000Z",
  "data": {
    "generatedAt": "2026-04-22T14:00:00.000Z",
    "accountCount": 4,
    "windowHours": 2
  }
}

Best Time

{
  "event": "best_time.recommendation_recomputed",
  "category": "best_time",
  "timestamp": "2026-04-22T03:00:00.000Z",
  "data": {
    "socialAccountId": "acc_123",
    "platform": "instagram",
    "isPersonalized": true,
    "postCount": 87,
    "timezone": "America/New_York"
  }
}

Referral

{
  "event": "referral.reward_earned",
  "category": "referral",
  "timestamp": "2026-04-22T14:37:00.000Z",
  "data": {
    "referralId": "ref_abc",
    "userId": "usr_xyz",
    "role": "referrer",
    "creditsAwarded": 10
  }
}

See the Webhooks Overview for the full list of 147 events across 26 categories.

Custom Payload Templates

If your endpoint expects a different shape (e.g. Slack, Discord), set a payloadTemplate on your webhook subscription. Available variables are:

{{event}}
{{category}}
{{timestamp}}
{{data}} — the full data object as JSON
{{data.any_field}} — any nested field from the event-specific payload

Unresolved variables are left in place (e.g. {{data.postId}} stays literal if the event doesn’t provide postId). See the overview page for Discord and Slack template examples.

Testing Locally

While developing:

Use a tunneling tool like ngrok or Cloudflare Tunnel to expose your local server.
Create a webhook subscription in Settings → Webhooks pointing at your tunnel URL.
Click the Test button on the subscription to send a sample event without triggering real activity.
Inspect the payload in Webhook.site if you want to see the raw request before writing a verifier.

If your endpoint fails 10 consecutive deliveries, the subscription is automatically disabled. Re-enable it from the dashboard after fixing the issue.

​Request Format

​Headers

​Envelope

​Signature Verification

​Example Payloads

​Post

​Approval

​Inbox

​WhatsApp

​Social Account

​Subscription

​AI

​Knowledge Hub

​Analytics

​Best Time

​Referral

​Custom Payload Templates

​Testing Locally

Request Format

Headers

Envelope

Signature Verification

Example Payloads

Post

Approval

Inbox

WhatsApp

Social Account

Subscription

AI

Knowledge Hub

Analytics

Best Time

Referral

Custom Payload Templates

Testing Locally