Quickstart Guide

Get SocialHook live in 5 minutes. Connect your first Meta platform account and start receiving webhooks with a few lines of code.

Estimated time: 5 minutes

Create your SocialHook account

After signing up, you'll land in your dashboard. From here you can connect your Meta accounts, configure your webhook URL, and view delivery logs. Your account includes a secret key for signing all webhook payloads.

Connect a Meta platform account

OAuth into Facebook, Instagram, or WhatsApp

Click Connect next to the platform you want to use. You'll be redirected to Meta's OAuth flow. SocialHook never stores your Meta password.

→Facebook: connect a Page you manage

→Instagram: requires an Instagram Business account

→WhatsApp: requires a WhatsApp Business number

Configure your webhook URL

Paste your endpoint and generate a secret key

In your dashboard, go to Webhook Settings and paste your server's POST endpoint URL. Generate a secret key — you'll use this to verify payload signatures.

For local development, use ngrok to expose your localhost:

shell

npx ngrok http 3000

Set up signature verification

Verify every payload before processing

Every delivery includes an X-SocialHook-Signature header. Verify this before processing any payload:

node.js

const crypto = require('crypto')

function verifySignature(rawBody, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex')
  return signature === expected
}

app.post('/webhook', express.raw({ type: '*/*' }), (req, res) => {
  const sig = req.headers['x-socialhook-signature']

  if (!verifySignature(req.body, sig, process.env.SOCIALHOOK_SECRET)) {
    return res.status(401).send('Unauthorized')
  }

  const payload = JSON.parse(req.body)
  // ... handle payload
  res.sendStatus(200)
})

Handle incoming events

Parse and act on webhook payloads

Once verified, parse the JSON payload and route on the event field:

node.js

const { platform, event, message, from } = payload

switch (event) {
  case 'message.received':
    console.log(`[${platform}] Message from ${from}: ${message.body}`)
    // Route to AI, CRM, n8n, etc.
    await handleInboundMessage(payload)
    break

  case 'conversation.started':
    // New conversation — create a CRM lead, send welcome message
    await createLead({ platform, from, timestamp: payload.timestamp })
    break

  default:
    console.log('Unhandled event:', event)
}

res.sendStatus(200) // Always respond 200

Important: Always return a 200 status immediately. If your server takes longer than 10 seconds to respond, SocialHook will treat the delivery as failed and retry.

You're live 🎉

Send a test message to your connected WhatsApp number, Facebook Page, or Instagram account. You should see a delivery appear in your SocialHook dashboard logs and a POST hit your server within 50ms.

Payload reference →Security guide