Outbound API

Wann du dies verwendest

1. API-Schlüssel holen

Öffne API-Schlüssel in deinem Dashboard und klicke auf Generieren. Du siehst den vollständigen Schlüssel einmal — kopiere ihn jetzt und speichere ihn sicher (z.B. in deinem Secrets Manager). Wenn du ihn verlierst, generiere einen neuen; der alte hört sofort auf zu funktionieren.

Schlüssel beginnen mit sk_live_ gefolgt von 64 Hex-Zeichen. Behandle ihn wie ein Passwort: nie in git committen, nie in Browser-Code preisgeben.

2. Endpunkt

POST https://api.socialhook.io/api/v1/outbound/<your_user_id>/send
Content-Type: application/json

Deine user_id wird in der URL auf der API-Schlüssel-Seite angezeigt. Der Pfad ist absichtlich benutzerbezogen, sodass ein geleakter Schlüssel nur ein Konto betreffen kann.

3. Authentifizierung

Wähle die Methode, die zu deinem Setup passt. Beide funktionieren mit demselben Endpunkt.

Methode A — Einfacher Schlüssel (n8n, Make, Zapier, No-Code-Tools)

Füge einen einzigen Header hinzu. Keine Signierung erforderlich.

X-Api-Key: <your_api_key>

# Method: POST
# URL:    https://api.socialhook.io/api/v1/outbound/<your_user_id>/send
# Header: X-Api-Key  →  sk_live_…
# Body (JSON):
{
  "platform": "whatsapp",
  "to": "447911123456",
  "message_text": "Hello from n8n!"
}

Methode B — Signierte Anfrage (HMAC-SHA256, benutzerdefinierte Server)

Erstelle die Signatur durch HMAC-SHA256-Hashing von <timestamp>.<raw_body> mit deinem API-Schlüssel, dann sende den kleingeschriebenen Hex-Digest im X-Socialhook-Signature Header mit dem Präfix sha256=. Anfragen mit Zeitstempeln, die mehr als 5 Minuten von der Serverzeit abweichen, werden abgelehnt.

X-Socialhook-Timestamp: <unix_seconds>
X-Socialhook-Signature: sha256=<hmac_hex>

const crypto = require('crypto');

const API_KEY = process.env.SOCIALHOOK_API_KEY;     // sk_live_…
const USER_ID = process.env.SOCIALHOOK_USER_ID;     // shown on the API key page

const body = JSON.stringify({
  platform: 'whatsapp',
  to: '447911123456',
  message_text: 'Hello from your SocialHook integration!',
});
const ts  = Math.floor(Date.now() / 1000).toString();
const sig = crypto
  .createHmac('sha256', API_KEY)
  .update(`${ts}.${body}`)
  .digest('hex');

const res = await fetch(
  `https://api.socialhook.io/api/v1/outbound/${USER_ID}/send`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Socialhook-Timestamp': ts,
      'X-Socialhook-Signature': `sha256=${sig}`,
    },
    body,
  }
);

if (!res.ok) throw new Error(await res.text());

# Drop your real API_KEY and USER_ID in here
TS=$(date +%s)
BODY='{"platform":"whatsapp","to":"447911123456","message_text":"Hello!"}'
SIG=$(printf "%s.%s" "$TS" "$BODY" | openssl dgst -sha256 -hmac "$API_KEY" | awk '{print $2}')

curl -X POST https://api.socialhook.io/api/v1/outbound/$USER_ID/send \
  -H "Content-Type: application/json" \
  -H "X-Socialhook-Timestamp: $TS" \
  -H "X-Socialhook-Signature: sha256=$SIG" \
  -d "$BODY"

4. Request-Body pro Plattform

{
  "platform": "whatsapp",
  "to": "447911123456",
  "message_text": "Hello from your integration!"
}

{
  "platform": "facebook",
  "to": "<recipient_psid>",
  "page_id": "<your_facebook_page_id>",
  "message_text": "Hi from SocialHook"
}

{
  "platform": "instagram",
  "to": "<recipient_psid>",
  "page_id": "<your_facebook_page_id>",
  "message_text": "Hey from SocialHook"
}

5. Antwort-Codes

Auto-Antwort (Endpunkt überspringen)

Wenn dein einziger ausgehender Bedarf das Antworten auf eingehende Nachrichten ist, musst du diesen Endpunkt gar nicht aufrufen. Wenn SocialHook einen Webhook an dich liefert, kann dein Server mit einem der folgenden antworten:

// Single reply
{ "reply": "Thanks — got your message!" }

// Or multiple in order
{ "replies": ["Thanks!", "We'll get back to you within an hour."] }

SocialHook sendet jede Antwort automatisch auf der richtigen Plattform und zeichnet sie im Chat-Thread auf. Antwortfehler blockieren die Zustellungsbestätigung nicht — dein Webhook wird trotzdem als DELIVERED markiert.

Wiederholungsschutz (signierte Anfragen)

Was als nächstes