Ii-webhook Beta

Nciphisa i-endpoint kwizitishi ezikhethiweyo

Kwi-Iisetingi → Umphuhlisi, i-endpoint nganye ingamamela zonke izitishi okanye izitishi ozikhethayo kuphela, zombini xa uyongeza naxa uyihlela kamva. Ii-endpoint ezenziwe phambi kokuba kubekho ukunqumla ngezitishi zihlala kuzo zonke izitishi de uzitshintshe.

Abaxhasi be-API ne-MCP baseta isihluzi esifanayo nge-sourceIds xa besenza okanye behlaziya i-endpoint. I-array engenanto ithetha yonke imithombo kwindawo yokusebenzela. Xa kukho ii-ID, iziganeko zeencoko nezemiyalezo zihanjiswa kuphela xa incoko yazo ingowomnye wemithombo ekhethiweyo. Iziganeko zenqanaba lendawo yokusebenzela, ezifana notshintsho loqhagamshelwano okanye lobulungu, azithunyelwa kwi-endpoint ehluzwe ngomthombo.

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

Yeka ukuhambisa into elahlwa ngumdibaniso wakho

Iarhente ephendula nge-API ivuswa yimpendulo yayo ngaphandle kokuba uthi akunjalo. Izihluzi ezintathu ongazikhethayo zinciphisa into efunyanwa yi-endpoint; zonke zivaliwe ngokwesiqhelo, ngoko i-endpoint esele ikhona ayitshintshi.

agentGroupIds

Iincoko ezingezamaqela eearhente adwelisiweyo kuphela. Oku kulandela ubunini, hayi isitishi incoko efike ngaso, ngoko incoko evela kwibhokisi engenayo ekwabelwana ngayo ifikelela kwiqela eliyiphetheyo. Iincoko ezingenaqela azihanjiswa, kwaye ngenxa yokuba amaqela ahlala abelwa emva kokuba incoko iqalile, i-conversation.created ihlala isenzeka phambi kokuba kubekho iqela lokuhambelana nalo.

customerMessagesOnly

Imiyalezo ebhalwe ngabathengi kuphela. Itsiba iimpendulo zeqela lakho, iinowuthi zangaphakathi, nantoni na ethunyelwe nge-API, i-MCP okanye ngumphenduli we-AI — kuquka iimpendulo ze-endpoint ngokwayo.

excludedSenderIds

Itsiba imiyalezo ethunyelwe ngamalungu eqela adwelisiweyo. Nika umdibaniso iakhawunti yawo yelungu leqela uze uyikhuphe ukuze uyeke ukuvuswa ziimpendulo zawo ngelixa usiva xa umntu ethatha incoko — umqondiso ofunwa yiarhente ye-AI ukuze irhoxe.

Izihluzi zemiyalezo zisebenza kwiziganeko ze-message.* kuphela; iintlobo zeziganeko zihlala zilulawulo lwayo yonke enye into. Isiganeko esihluziweyo siyalahlwa phambi kokuba sibe kukuhanjiswa, ngoko asikubizi nto kwaye asize siboniswe njengokungaphumeleli. Umthwalo ne-apiVersion azitshintshi nokuba kunjani.

Qokelela imiyalezo emininzi ibe kukuhanjiswa okunye

Umsebenzisi ofunda wonke umsonto xa evuka akazuzi nto kukuhanjiswa okune okwahlukeneyo kwimizuzwana elishumi. Seta i-coalesceSeconds kwaye imiyalezo yencoko enye iqokelelwa ixesha elingako, emva koko ithunyelwe njengokuhanjiswa okunye. Ivaliwe ngokwesiqhelo; ii-endpoint ezingenayo ziqhubeka zifumana umyalezo ngamnye wodwa.

Ukuhanjiswa okuqokelelweyo kufika njenge-conversation.activity ephethe incoko nazo zonke ii-id zemiyalezo eziqokelelweyo, ngoko funda umsonto kanye endaweni yomyalezo ngamnye. Le kuphela kwesetingi etshintsha imo yento oyifumanayo, yiyo loo nto kufuneka uyikhethe. Ezinye izihluzi zakho zisasebenza — umyalezo okhutshwe zizo awuze ujoyine iqela. Incoko nganye inefestile yayo, kwaye ukuzama kwakhona kuthatha iqela njengokuhanjiswa okunye.

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

Ii-endpoint ezingemva kwe-bearer okanye kwe-API-key auth

Ukuba umamkeli wakho ungemva kwesango elifuna i-header, yongeze phantsi kwe-Ii-header ezilungiselelweyo xa usenza okanye uhlela i-endpoint, okanye uthumele i-headers ukusuka kwi-API. Amaxabiso afihlwa ngekhowudi xa egciniwe kwaye akaze abuyiswe — i-header egciniweyo ibuya njengegama kuphela, kwaye ukuphinda uthumele elo gama lodwa kugcina ixabiso eligciniweyo. Thumela i-array engenanto ukuze ususe zonke ii-header.

Ukuhambisa i-endpoint kumsingathi owahlukileyo kususa ukuphinda kusetyenziswe: amaxabiso agciniweyo kufuneka aphinde afakwe, ngoko iinkcukacha zokungena azize zidluliselwe kwindawo ezingazange zikhutshelwe yona. Ukutshintsha indlela kuphela kuyazigcina.

Ii-header zeSonny ziphumelela kwezakho, ngoko i-header elungiselelweyo ayinakuze ithathe indawo ye-sonny-signature, i-content-type, okanye ii-header zobuni bokuhanjiswa. Khetha ukuqinisekisa umtyikityo apho unako: ungqinisisa wonke umthwalo, ngelixa ithokheni engatshintshiyo ichonga kuphela obizayo.

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

Ukhuseleko nokuthembeka

Umzimba okrwada otyikityiweyo

I-HMAC-SHA256 igubungela i-Unix timestamp, ichaphaza nomzimba wesicelo we-UTF-8 ongachukunyiswanga.

Ukhuseleko ekudlalweni kwakhona

Yala ii-timestamp ezingaphezu kwemizuzu emihlanu kwixesha elidlulileyo okanye elizayo, nokuba i-HMAC isebenza.

Ukuzama kwakhona okuthembekileyo

Iimpendulo ezingezizo ze-2xx ziphinda zizame emva kwe-1m, 5m, 30m, 2h, 6h. Inzame 6 yeyokugqibela.

Isivumelwano sesicelo

sonny-signature

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

sonny-event

Uhlobo lwesiganeko, lokuthumela ngokukhawuleza.

sonny-delivery-id

I-ID ezinzileyo yokungaphindi nokuxhasa.

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 umtyikityo

Funda umzimba okrwada kuqala. Ukwahlula i-JSON uze uphinde uyilungelelanise kutshintsha izithuba kwaye kwenza umtyikityo osebenzayo ungaphumeleli.

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");
}

Ikhathalogu yeziganeko

webhook.heartbeat

Ithunyelwa rhoqo emva kwemizuzu emihlanu kubabhalisi abavuliweyo (kuquka *), nokuba akukho miyalezo mitsha. Isebenzisa indlela eqhelekileyo yokuhanjiswa esayiniweyo/yokuzama kwakhona kwaye ayihoyi izihluzi zeencoko. Yenza isilumkiso xa ii-heartbeat zingekho okanye zindala; ayikhangeli iincoko ezilinde impendulo.

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

contact.created

Oqhagamshelwano wenziwe.

{"contactId":"cm_contact_id"}

contact.updated

Oqhagamshelwano uhlaziyiwe okanye udityanisiwe.

{"contactId":"cm_contact_id"}

contact.deleted

Oqhagamshelwano ugcinwe kuvimba okanye udityaniswe nomnye oqhagamshelwano. Usenokufundwa nge-archived=true.

{"contactId":"cm_contact_id"}

contact.erased

Oqhagamshelwano ucinywe ngokusisigxina (umzekelo isicelo sokucima se-GDPR) kunye nazo zonke iincoko zakhe, imiyalezo nezinto eziqhotyoshelweyo. Akasenakufundwa; cima nayiphi na ikopi oyigcinileyo.

{"contactId":"cm_contact_id"}

conversation.created

Incoko yenziwe.

{"conversationId":"cm_conversation_id"}

conversation.updated

Incoko itshintshile.

{"conversationId":"cm_conversation_id"}

conversation.closed

Incoko ivaliwe.

{"conversationId":"cm_conversation_id"}

conversation.deleted

Incoko isiwe enkunkumeni kwaye iphumile kwi-API yoluntu.

{"conversationId":"cm_conversation_id"}

message.created

Umyalezo okanye inowuthi yangaphakathi yenziwe. Imeko nomboniso omfutshane womyalezo ziyabandakanywa xa zikhona; umbhalo wenowuthi yangaphakathi awuze ubandakanywe.

{"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 ethunyelweyo ihleliwe kumbhalo wencoko. Ii-imeyile ezihanjisiweyo azitshintshi.

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

tag.created

Ithegi yenziwe.

{"tagId":"cm_tag_id"}

tag.updated

Ithegi ihlaziyiwe.

{"tagId":"cm_tag_id"}

tag.deleted

Ithegi icinyiwe.

{"tagId":"cm_tag_id"}

member.invited

Ilungu lendawo yokusebenzela limenyiwe.

{"invitationId":"cm_invitation_id"}

member.updated

Indima okanye imeko yelungu itshintshile.

{"memberId":"cm_membership_id"}

member.removed

Ilungu lisusiwe.

{"memberId":"cm_membership_id"}

invitation.accepted

Isimemo sendawo yokusebenzela samkelwe.

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

invitation.cancelled

Isimemo esilindileyo sendawo yokusebenzela sirhoxisiwe.

{"invitationId":"cm_invitation_id"}

conversation.activity

Imiyalezo yencoko enye, idityaniswe kukuhanjiswa okunye. Iquka umfanekiso womyalezo ngamnye xa ukhona. Ithunyelwa endaweni ye-message.created kwii-endpoint ezinexesha lokudibanisa, ayinakubhaliselwa ngqo.

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

webhook.test

Isiganeko sovavanyo esicelwe ngumlawuli.

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

Indlela yokuhanjiswa

• Buyisa nayiphi na imeko ye-2xx kwisithuba semizuzwana eli-10 ukuze uphawule ukuhanjiswa njengokuphumeleleyo.
• Gcina abaphathi bengaphindi isiphumo. Sebenzisa i-id yesiganeko okanye i-sonny-delivery-id ukuze ungakhathali ngeziphindiweyo.
• Ukuthunyelwa kwenye indawo akulandelwa. Hlaziya i-URL ye-endpoint kwiSonny endaweni yoko.
• Imizimba yeempendulo inomda kwaye zii-4 KiB zokuqala kuphela ezigcinwayo ukuze kuhlolwe.
• Khetha Vavanya ukuze uthumele isiganeko esithi webhook.test. Khetha Ukuhanjiswa ukuze uhlole iziganeko ezingama-50 zamva nje. Xa ukuhanjiswa kufikelela ekungaphumeleleni kokugqibela, khetha Phinda uzame ukuze ukuthumele kwakhona.

Amaxwebhu anxulumeneyo

• I-API yoluntuBeta

  Hlela uze uvumelanise iincoko, yabelana ngeenkcukacha zabathengi, funda iingxelo uze uthumele iifayile ngezitshixo ze-API ezinemida.

• Ibhokisi engenayo

  Qonda imeko, ukubaluleka, ukwabela, ukulalisa, izenzo ezininzi ngaxeshanye nezinqumelo zekhibhodi.

• Abaqhagamshelwano

  Funda ukuba abaqhagamshelwano benziwa njani, balawulwa njani, bafakwa njani iithegi nokuba badityaniswa njani kwiSonny.

• Iqela neendima

  Mema abasebenzisi, yenza amaqela, uze uqonde ufikelelo lomnini, umlawuli, iarhente nombukeli.