Webhooks - SocialAPI.AI

Instead of polling the API, register a webhook endpoint and SocialAPI will POST a signed payload to your server whenever a new comment, DM, review, or mention arrives.

Register an endpoint

Endpoints can be registered in the dashboard under Webhooks → Add Endpoint, or via the API:

curl -X POST https://api.social-api.ai/v1/webhooks \
  -H "Authorization: Bearer $SOCAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://app.example.com/webhooks/socapi",
    "events": ["comment.received", "dm.received", "review.received"]
  }'

Response (HTTP 201):

{
  "id": "wh_01HZ9X3Q4R5M6N7P8V2K0W1J",
  "url": "https://app.example.com/webhooks/socapi",
  "events": ["comment.received", "dm.received", "review.received"],
  "secret": "a3f8c2e1b9d4f7a6c5e0b3d2f1a8e7c4b9d6f3a2e5c8b1d4f7a0e3c6b9d2f5a8",
  "message": "Store the secret securely. It will not be shown again."
}

The secret is returned once. Store it immediately in your environment. It cannot be retrieved again. You use it to verify incoming signatures.

Endpoint URLs must use HTTPS. HTTP URLs are rejected with 400.

When you create an endpoint, SocialAPI sends a verification ping to your URL. Your server must respond with a 2xx status code or the endpoint will not be saved. Make sure your server is running and reachable before registering.

Event types

Event	When it fires
`comment.received`	A new comment arrives on any connected account
`dm.received`	A new direct message arrives (may include `metadata.referral` if the DM originated from an ad)
`dm.sent`	Your account sent a direct message (echo confirmation from Meta).
`dm.referral`	A user clicked an ad or referral link without sending a message. The interaction has empty content and includes `metadata.referral`.
`review.received`	A new review arrives (Google Business Profile)
`mention.received`	Your account is mentioned on a supported platform

You can subscribe to any combination. Pass all six to receive everything:

[
  "comment.received",
  "dm.received",
  "dm.sent",
  "dm.referral",
  "review.received",
  "mention.received"
]

Payload format

Every webhook POST has a JSON body with an event field and a data field containing the full interaction object:

{
  "event": "comment.received",
  "data": {
    "id": "sapi_cmt_aW5zdGFncmFtOjE3ODQxNDA1",
    "type": "comment",
    "platform": "instagram",
    "account_id": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J",
    "author": {
      "id": "10215054824",
      "name": "Jane Smith",
      "avatar_url": "https://example.com/avatar.jpg"
    },
    "content": {
      "text": "Love this product!",
      "media": []
    },
    "received_at": "2026-03-01T14:30:00Z",
    "metadata": {}
  }
}

The data object is the same Interaction shape returned by GET /accounts/{id}/comments (and the equivalent DM, review, and mention endpoints). The id field is a stable SocialAPI interaction ID - see Interaction IDs.

Referral metadata

When a DM originates from an ad click (Instagram CTD or Facebook CTM ads), the interaction includes referral context in metadata.referral:

{
  "event": "dm.received",
  "data": {
    "id": "sapi_dm_aW5zdGFncmFtOm1pZC5yZWYx",
    "type": "dm",
    "platform": "instagram",
    "account_id": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J",
    "author": { "id": "17846744073097661" },
    "content": { "text": "I saw your ad!" },
    "received_at": "2026-03-01T14:30:00Z",
    "metadata": {
      "referral": {
        "ad_id": "120210572164750432",
        "source": "ADS",
        "type": "OPEN_THREAD",
        "ads_context_data": {
          "ad_title": "Spring Sale 25% Off",
          "photo_url": "https://scontent.xx.fbcdn.net/..."
        }
      }
    }
  }
}

Only non-empty referral fields are included. dm.referral events (standalone ad clicks without a message) have empty content.text and always include metadata.referral.

Request headers

Every webhook request includes:

Header	Value
`Content-Type`	`application/json`
`X-SocialAPI-Signature`	`sha256=<hmac-sha256-hex>`
`X-SocialAPI-Event`	The event type, e.g. `comment.received`

Verifying signatures

Always verify the X-SocialAPI-Signature header before processing a webhook. This confirms the payload came from SocialAPI and was not tampered with. The signature is HMAC-SHA256 of the raw request body, using your endpoint secret as the key, prefixed with sha256=.

Node.js
Python
Go

import crypto from "crypto";

function verifySignature(secret, rawBody, signatureHeader) {
  const expected = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signatureHeader)
  );
}

// Express example
app.post("/webhooks/socapi", express.raw({ type: "application/json" }), (req, res) => {
  const sig = req.headers["x-socialapi-signature"];
  if (!verifySignature(process.env.SOCAPI_WEBHOOK_SECRET, req.body, sig)) {
    return res.status(401).send("Invalid signature");
  }
  const event = JSON.parse(req.body);
  // handle event.event and event.data
  res.sendStatus(200);
});

import hmac
import hashlib

def verify_signature(secret: str, raw_body: bytes, signature_header: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header)

# Flask example
@app.route("/webhooks/socapi", methods=["POST"])
def webhook():
    sig = request.headers.get("X-SocialAPI-Signature", "")
    if not verify_signature(os.environ["SOCAPI_WEBHOOK_SECRET"], request.data, sig):
        abort(401)
    event = request.json
    # handle event["event"] and event["data"]
    return "", 200

func verifySignature(secret string, body []byte, sigHeader string) bool {
    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write(body)
    expected := "sha256=" + hex.EncodeToString(mac.Sum(nil))
    return hmac.Equal([]byte(expected), []byte(sigHeader))
}

Use a constant-time comparison (timingSafeEqual / compare_digest / hmac.Equal) to prevent timing attacks. A simple string equality check is not safe.

Responding to webhooks

Your endpoint must return an HTTP 2xx status within 10 seconds. The webhook HTTP client enforces a 10-second timeout per delivery attempt. Any non-2xx response or a timeout is treated as a delivery failure. Return 200 immediately and process the event asynchronously if your handler does heavier work.

Retry behavior

Failed deliveries are automatically retried up to 5 attempts with exponential backoff:

Attempt	Delay
1	Immediate
2	~30 seconds
3	~5 minutes
4	~30 minutes
5	~3 hours

After 5 failed attempts, the delivery is marked failed and no further retries occur.

Managing endpoints

List endpoints

curl https://api.social-api.ai/v1/webhooks \
  -H "Authorization: Bearer $SOCAPI_KEY"

Get endpoint details

Retrieve a single endpoint with delivery statistics (delivered/failed counts for the last 24 hours and 7 days). The secret is shown as a hint (last 4 characters only).

curl https://api.social-api.ai/v1/webhooks/{id} \
  -H "Authorization: Bearer $SOCAPI_KEY"

Update an endpoint

Change the URL, subscribed events, or toggle delivery on/off. All fields are optional; provide at least one.

curl -X PATCH https://api.social-api.ai/v1/webhooks/{id} \
  -H "Authorization: Bearer $SOCAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"is_active": false}'

Delete an endpoint

curl -X DELETE https://api.social-api.ai/v1/webhooks/{id} \
  -H "Authorization: Bearer $SOCAPI_KEY"

Deleting an endpoint stops all future deliveries immediately. In-flight jobs already queued may still attempt delivery once.

Delivery monitoring

Every webhook delivery is recorded with its status, HTTP response code, and duration. You can inspect delivery history, view individual attempts, send test payloads, and retry failed deliveries.

Endpoint	Description
`GET /v1/webhooks/{id}/deliveries`	List deliveries (filterable by `status` and `event_type`, cursor-paginated)
`GET /v1/webhooks/{id}/deliveries/{did}`	Full delivery detail including payload and all retry attempts
`POST /v1/webhooks/{id}/deliveries/{did}/retry`	Re-enqueue a failed delivery
`POST /v1/webhooks/{id}/test`	Send a test payload to verify your endpoint is working

See the API Reference for full request and response schemas.

Security best practices

Always verify signatures - never trust a webhook payload without checking X-SocialAPI-Signature
Store your secret in an environment variable - never hardcode it or commit it to source control
Use HTTPS - HTTP endpoints are rejected at registration time
Respond quickly - return 200 before doing heavy processing to avoid timeouts and spurious retries
Make handlers idempotent - retries mean the same event may arrive more than once; use the interaction id to deduplicate

Documentation Index

​Register an endpoint

​Event types

​Payload format

​Referral metadata

​Request headers

​Verifying signatures

​Responding to webhooks

​Retry behavior

​Managing endpoints

​List endpoints

​Get endpoint details

​Update an endpoint

​Delete an endpoint

​Delivery monitoring

​Security best practices

Register an endpoint

Event types

Payload format

Referral metadata

Request headers

Verifying signatures

Responding to webhooks

Retry behavior

Managing endpoints

List endpoints

Get endpoint details

Update an endpoint

Delete an endpoint

Delivery monitoring

Security best practices