Ama-webhook Beta

Khawulela i-endpoint eziteshini ezikhethiwe

Ku-Izilungiselelo → Unjiniyela, i-endpoint ngayinye ingalalela zonke iziteshi noma iziteshi ozikhethayo kuphela, kokubili lapho uyengeza nalapho uyihlela kamuva. Ama-endpoint adalwa ngaphambi kokuba kube khona ukukhawulela iziteshi ahlala kuzo zonke iziteshi uze uwashintshe.

Amaklayenti e-API ne-MCP asetha isihlungi esifanayo nge-sourceIds lapho edala noma ebuyekeza i-endpoint. I-array engenalutho isho yonke imithombo endaweni yokusebenza. Uma ama-ID ekhona, imicimbi yezingxoxo neyemilayezo ilethwa kuphela uma ingxoxo yayo ingeyomunye wemithombo ekhethiwe. Imicimbi yezinga lendawo yokusebenza, njengezinguquko zoxhumana nabo noma zobulungu, ayithunyelwa ku-endpoint ehlungwe ngomthombo.

{
  "name": "Product A agent",
  "url": "https://agent.example.com/sonny",
  "events": ["conversation.created", "message.created"],
  "sourceIds": ["cm_source_id"]
}

Yeka ukuletha lokho okulahlwa ukuhlanganiswa kwakho

I-ejenti ephendula nge-API ivuswa yimpendulo yayo uqobo ngaphandle uma usho okunye. Izihlungi ezintathu ozikhethelayo zinciphisa lokho i-endpoint ekutholayo; zonke zivaliwe ngokuzenzakalela, ngakho i-endpoint ekhona ayishintshi.

agentGroupIds

Izingxoxo eziphethwe amaqembu ama-ejenti abaliwe kuphela. Lokhu kulandela ubunikazi, hhayi isiteshi ingxoxo efike ngaso, ngakho ingxoxo evela ku-inbox eyabiwe ifinyelela eqenjini eliyiphethe. Izingxoxo ezingenalo iqembu azilethwa, futhi ngoba amaqembu avame ukwabelwa ngemuva kokuqala kwengxoxo, i-conversation.created ivame ukufika ngaphambi kokuba kube neqembu elingafaniswa.

customerMessagesOnly

Imilayezo ebhalwe amakhasimende kuphela. Yeqa izimpendulo zethimba lakho, amanothi angaphakathi, nanoma yini ethunyelwe nge-API, MCP noma umphenduli we-AI — kuhlanganise nezimpendulo zale endpoint uqobo.

excludedSenderIds

Yeqa imilayezo ethunyelwe ozakwenu ababaliwe. Nika ukuhlanganiswa i-akhawunti yayo yozakwenu bese uyikhipha ukuze ingavuki ngezimpendulo zayo, kodwa isezwa lapho umuntu ethatha ingxoxo — uphawu i-ejenti ye-AI eludingayo ukuze ihoxe.

Izihlungi zemilayezo zisebenza kuphela emicimbini ye-message.*; izinhlobo zemicimbi zihlala ziyisilawuli sakho konke okunye. Umcimbi ohlungiwe uyalahlwa ngaphambi kokuba ube ukulethwa, ngakho awukubizi lutho futhi awusoze waboniswa njengokwehluleka. I-payload ne-apiVersion akushintshi nhlobo.

Qoqa uchungechunge lwemilayezo lube ukulethwa okukodwa

Umthengi ofunda lonke uchungechunge lapho evuka akazuzi lutho ekulethweni okune okuhlukene emizuzwini eyishumi. Setha i-coalesceSeconds bese imilayezo yengxoxo eyodwa iqoqwa isikhathi esingako, bese ithunyelwa njengokulethwa okukodwa. Kuvaliwe ngokuzenzakalela; ama-endpoint angenakho aqhubeka ethola umlayezo ngamunye wodwa.

Ukulethwa okuqoqiwe kufika njenge-conversation.activity kuphethe ingxoxo nawo wonke ama-id emilayezo aqoqiwe, ngakho funda uchungechunge kanye esikhundleni sokufunda ngomlayezo ngamunye. Lesi yisilungiselelo esisodwa esishintsha isimo salokho okutholayo, yingakho kufanele usivule ngokwakho. Ezinye izihlungi zakho zisasebenza — umlayezo okhishwe yizo awusoze wajoyina iqoqo. Ingxoxo ngayinye inewindi layo, futhi ukuzama futhi kuphatha iqoqo njengokulethwa okukodwa.

{
  "type": "conversation.activity",
  "data": {
    "conversationId": "cm_conversation_id",
    "messageIds": ["cm_first_message", "cm_second_message"]
  }
}

Ama-endpoint angemuva kokuqinisekisa nge-bearer noma ngokhiye we-API

Uma umamukeli wakho engemuva kwe-gateway edinga i-header, yengeze ngaphansi kuka-Ama-header angokwezifiso lapho udala noma uhlela i-endpoint, noma uthumele i-headers nge-API. Amanani agcinwa ebethelwe futhi awasoze abuyiswa — i-header egciniwe ibuya njengegama kuphela, futhi ukuphinda uthumele lelo gama lilodwa kugcina inani eligciniwe. Thumela i-array engenalutho ukuze ukhiphe wonke ama-header.

Ukuhambisa i-endpoint kuya ku-host ehlukile kususa ukusetshenziswa kabusha: amanani agciniwe kufanele afakwe kabusha, ukuze imininingwane yokungena ingadluliselwa endaweni engakhishelwanga yona. Ukushintsha indlela kuphela kuyawagcina.

Ama-header e-Sonny uqobo ahamba phambili kunawakho, ngakho i-header yangokwezifiso ayisoze yathatha indawo ye-sonny-signature, content-type, noma ama-header okuhlonza ukulethwa. Khetha ukuqinisekisa isiginesha lapho ungakwazi khona: iqinisekisa yonke i-payload, kanti ithokheni engashintshi ihlonza kuphela oshayayo.

{
  "name": "Gateway",
  "url": "https://api.example.com/hooks/sonny",
  "events": ["conversation.created"],
  "headers": [{ "name": "Authorization", "value": "Bearer …" }]
}

Ukuphepha nokwethembeka

Umzimba ongaguquliwe osayiniwe

I-HMAC-SHA256 ihlanganisa isitembu sesikhathi se-Unix, ichashazi, nomzimba wesicelo we-UTF-8 ongathintiwe.

Ukuvikela ekuphindweni

Yenqaba izitembu zesikhathi ezingaphezu kwemizuzu emihlanu esikhathini esedlule noma esizayo, ngisho noma i-HMAC ivumelekile.

Ukuzama futhi okuqinile

Izimpendulo ezingezona ezingu-2xx ziphinda zizame ngemuva kuka-1m, 5m, 30m, 2h, 6h. Umzamo 6 ungowokugcina.

Isivumelwano sesicelo

sonny-signature

t=<unix-seconds>,v1=<sha256-hex>

sonny-event

Uhlobo lomcimbi, lokudlulisela ngokushesha.

sonny-delivery-id

I-ID engaguquki ye-idempotency nosizo.

user-agent

Sonny-Webhooks/1.0

{
  "id": "cm_event_id",
  "type": "message.created",
  "apiVersion": "2026-07-15",
  "createdAt": "2026-07-15T12:00:00.000Z",
  "data": {
    "conversationId": "cm_conversation_id",
    "messageId": "cm_message_id"
  }
}

Qinisekisa isiginesha

Funda umzimba ongaguquliwe kuqala. Ukuhlaziya i-JSON bese uyihlela kabusha kushintsha izikhala futhi kwenza isiginesha evumelekile yehluleke.

import { createHmac, timingSafeEqual } from "node:crypto";

const rawBody = await request.text(); // do not parse/re-serialize first
const signature = request.headers.get("sonny-signature");
const secret = process.env.SONNY_WEBHOOK_SECRET;
if (!signature || !secret) throw new Error("Missing webhook signature or secret");
const { t, v1 } = Object.fromEntries(signature.split(",").map(p => p.split("=")));

if (!/^\d+$/.test(t) || !/^[a-f0-9]{64}$/i.test(v1)) {
  throw new Error("Malformed signature");
}
if (Math.abs(Math.floor(Date.now() / 1000) - Number(t)) > 300) {
  throw new Error("Stale webhook");
}
const expected = createHmac("sha256", secret)
  .update(`${t}.${rawBody}`).digest("hex");
if (!timingSafeEqual(Buffer.from(v1, "hex"), Buffer.from(expected, "hex"))) {
  throw new Error("Invalid signature");
}

Uhlu lwemicimbi

webhook.heartbeat

Kuthunyelwa njalo emizuzwini emihlanu kubabhalisile abavuliwe (kuhlanganise no-*), ngisho noma ingekho imilayezo emisha. Kusebenzisa indlela evamile yokulethwa esayiniwe/yokuzama futhi futhi akunaki izihlungi zezingxoxo. Yazisa uma ama-heartbeat engekho noma emadala; akuskeni izingxoxo ezilinde impendulo.

{"intervalSeconds":300,"nextExpectedAt":"2026-09-29T16:05:00.000Z"}

contact.created

Oxhumana naye udaliwe.

{"contactId":"cm_contact_id"}

contact.updated

Oxhumana naye ubuyekeziwe noma uhlanganisiwe.

{"contactId":"cm_contact_id"}

contact.deleted

Oxhumana naye ugcinwe kungobo yomlando noma uhlanganiswe nomunye. Usengafundwa nge-archived=true.

{"contactId":"cm_contact_id"}

contact.erased

Oxhumana naye usulwe unomphela (isibonelo isicelo sokusula se-GDPR) nazo zonke izingxoxo zakhe, imilayezo nokunamathiselwe. Akasakwazi ukufundwa; susa noma yimaphi amakhophi owagcinayo.

{"contactId":"cm_contact_id"}

conversation.created

Ingxoxo idaliwe.

{"conversationId":"cm_conversation_id"}

conversation.updated

Ingxoxo ishintshile.

{"conversationId":"cm_conversation_id"}

conversation.closed

Ingxoxo ivaliwe.

{"conversationId":"cm_conversation_id"}

conversation.deleted

Ingxoxo ihanjiswe kudoti futhi yaphuma ku-API yomphakathi.

{"conversationId":"cm_conversation_id"}

message.created

Kudalwe umlayezo noma inothi langaphakathi. Umongo nokubuka kuqala okufushane komlayezo kufakiwe uma kutholakala; umbhalo wenothi langaphakathi awusoze wafakwa.

{"conversationId":"cm_conversation_id","messageId":"cm_message_id","context":{"sourceId":"cm_source_id","sourceName":"Shopstar Go","storeName":"Shiney Store","inboxId":"cm_inbox_id","inboxName":"Go support","agentGroupId":"cm_group_id","agentGroupName":"Support","identityVerified":true,"status":"open","lastRepliedAt":"2026-09-25T09:00:00.000Z"},"message":{"id":"cm_message_id","type":"incoming","senderType":"human","senderId":null,"senderName":"Shiney","textPreview":"Could you check my bill?","textTruncated":false}}

message.updated

Impendulo ethunyelwe ihlelwe embhalweni wengxoxo. Ama-imeyili asethunyelwe ahlala engashintshile.

{"conversationId":"cm_conversation_id","messageId":"cm_message_id"}

tag.created

Ithegi lidaliwe.

{"tagId":"cm_tag_id"}

tag.updated

Ithegi libuyekeziwe.

{"tagId":"cm_tag_id"}

tag.deleted

Ithegi lisusiwe.

{"tagId":"cm_tag_id"}

member.invited

Ilungu lendawo yokusebenza limenyiwe.

{"invitationId":"cm_invitation_id"}

member.updated

Indima noma isimo selungu sishintshile.

{"memberId":"cm_membership_id"}

member.removed

Ilungu likhishiwe.

{"memberId":"cm_membership_id"}

invitation.accepted

Isimemo sendawo yokusebenza samukelwe.

{"invitationId":"cm_invitation_id","memberId":"cm_membership_id"}

invitation.cancelled

Isimemo sendawo yokusebenza esilindile sikhanseliwe.

{"invitationId":"cm_invitation_id"}

conversation.activity

Imilayezo yengxoxo eyodwa, iqoqwe ekulethweni okukodwa. Kufaka isithombe somlayezo ngamunye uma sitholakala. Kuthunyelwa esikhundleni se-message.created kuma-endpoint anewindi lokuqoqa, akusoze kwabhaliselwa ngqo.

{"conversationId":"cm_conversation_id","messageIds":["cm_message_id","cm_other_message_id"]}

webhook.test

Umcimbi wokuhlola oceliwe ngumlawuli.

{"message":"This is a test webhook from Sonny."}

Indlela ukulethwa okusebenza ngayo

• Buyisa noma yisiphi isimo esingu-2xx kungakapheli imizuzwana engu-10 ukuze ukulethwa kumakwe njengokuphumelele.
• Gcina izibambi zakho zingu-idempotent. Sebenzisa umcimbi id noma sonny-delivery-id ukuze unganaki okuphindiwe.
• Ukuqondisa kabusha akulandelwa. Esikhundleni salokho, buyekeza i-URL ye-endpoint ku-Sonny.
• Imizimba yezimpendulo inomkhawulo futhi kugcinwa kuphela ama-4 KiB okuqala ukuze kuhlolwe izinkinga.
• Khetha u-Hlola ukuze uthumele umcimbi we-webhook.test. Khetha u-Ukulethwa ukuze uhlole imicimbi engu-50 yakamuva. Lapho ukulethwa kufinyelela ekwehlulekeni kokugcina, khetha u-Zama futhi ukuze ukuthumele futhi.

Imibhalo ehlobene

• I-API yomphakathiBeta

  Hlela futhi uvumelanise izingxoxo, yabelana ngomongo wamakhasimende, funda imibiko, futhi uthumele amafayela ngokhiye be-API abanemikhawulo.

• I-inbox

  Qonda izimo, ukubaluleka, ukwabela, ukuhlehlisa, izenzo zeqoqo, nezinqamuleli zekhibhodi.

• Oxhumana nabo

  Funda ukuthi oxhumana nabo badalwa, baphathwa, bafakwa amathegi, futhi bahlanganiswa kanjani ku-Sonny.

• Ithimba nezindima

  Mema abasebenzisi, dala amathimba, futhi uqonde ukufinyelela komnikazi, umlawuli, i-ejenti, nombukeli.