Webhooks

Dohodne končne točke webhook za Meta kanale: Facebook Messenger, Instagram DM in WhatsApp.

Hitre dejstvice#

Webhooks se prejemajo na helpstack.eu; ta URL za povratni klic registrirate na nadzorni plošči aplikacije Meta. Žeton za preverjanje in skrivnost aplikacije konfigurira HelpStack (glejte okoljske spremenljivke, navedene spodaj).

Kako deluje rokovanje (vsi ponudniki)#

Meta preveri webhook tako, da pošlje zahtevo GET s tremi parametri poizvedbe. HelpStack odmeva izziv samo če se žeton za preverjanje ujema.

GET /api/webhooks/facebook
  ?hub.mode=subscribe
  &hub.verify_token=TOKEN
  &hub.challenge=CHALLENGE

• Če se TOKEN ujema s konfiguriranim žetonom za preverjanje → odgovori z 200 in surovo vrednostjo CHALLENGE.
• V nasprotnem primeru → odgovori s 403.

Kako deluje preverjanje podpisa (vsi ponudniki)#

Vsak POST nosi glavo x-hub-signature-256. Podpis se izračuna nad surovo vsebino zahteve z HMAC-SHA256, zaklenjenim z FACEBOOK_APP_SECRET, z predpono sha256=.

x-hub-signature-256: sha256=<šestnajstiški HMAC-SHA256(rawBody, FACEBOOK_APP_SECRET)>

Primer v Node.js (kako izračunati/preveriti):

import crypto from 'node:crypto';

function verifySignature(rawBody, headerValue, appSecret) {
  const expected =
    'sha256=' +
    crypto.createHmac('sha256', appSecret).update(rawBody).digest('hex');
  return headerValue === expected;
}

Pozor — uporabite surovo telo. Podpis se izračuna nad točnimi bajti, ki jih je poslala Meta. HelpStack prebere telo kot surovo besedilo pred razčlenjevanjem JSON. Če gradite lastni preverjevalnik, ne znova serializirajte razčlenjenega objekta JSON (vrstni red ključev/presledki se bodo razlikovali in podpis se ne bo ujemal). Zajemite surovi niz telesa in izvajajte HMAC nad njim.

Facebook / Messenger#

Oblika dohodne koristne obremenitve. Telo vsebuje polje entry[]. Vsak vnos ima bodisi:

• entry[].messaging[] — podedovana oblika Messenger, ali
• entry[].changes[] — novejša oblika.

Ujemanje kanala in obdelava. Upravljalnik ujame kanal po facebookPageId / credentials.pageId, nato:

1. Ustvari ali posodobi pogovor, zaključen po pošiljateljevem PSID.
2. Shrani dohodno sporočilo.
3. Pridobi profil pošiljatelja in prenese priloge v shrambo.
4. Odda dogodek v realnem času na nadzorno ploščo.

Instagram#

Ujame kanale, upravljane prek OAuth, po id-ju računa Instagram. Rokovanje in preverjanje podpisa delujeta enako kot pri Facebooku.

WhatsApp#

Oblika dohodne koristne obremenitve. Telo vsebuje entry[].changes[].value s messages[] in contacts[]. Upravljalnik ujame kanal po credentials.phoneNumberId in zaključi pogovor po pošiljateljevi telefonski številki.

Okoljske spremenljivke#

Registracija na nadzorni plošči aplikacije Meta#

Za Messenger (enak vzorec velja za Instagram in WhatsApp z njihovimi končnimi točkami):

1. Na nadzorni plošči aplikacije Meta odprite produkt (Messenger / Instagram / WhatsApp) → Webhooks.
2. URL za povratni klic: https://helpstack.eu/api/webhooks/facebook (Instagram: .../api/webhooks/instagram, WhatsApp: .../api/webhooks/whatsapp.)
3. Žeton za preverjanje: vrednost, ki ste jo nastavili v FACEBOOK_VERIFY_TOKEN (ali žeton za posameznega ponudnika).
4. Kliknite Preveri in shrani — Meta pošlje rokovanje GET; uspešno, ko se žeton ujema.
5. Naročite se na polja: naročite se na polja messages / messaging, da se dostavijo dogodki sporočil.
6. Zagotovite, da se Skrivnost aplikacije ujema z FACEBOOK_APP_SECRET, da preverjanje podpisa uspe pri POST.

Po shranjevanju pošljite testno sporočilo na stran/račun — prikazati se mora kot nov pogovor na nadzorni plošči.

Sorodne teme#

• Referenca API
• E-poštni kanal
• Navodila za kanale
• Slovar