Tumanggap ng mga webhook at i-verify ang mga lagda

Itinutulak ng Ody ang mga event ng workspace — mga bagong mensahe, resulta ng tawag, pagbabago ng contact — sa mga HTTPS endpoint na iyong inirerehistro sa pamamagitan ng API, na ang bawat paghahatid ay nilagdaan ayon sa Standard Webhooks spec upang mapatunayan mo na ito ay nagmula sa Ody.

Bago ka magsimula

• Kailangan mo ng API key na may webhooks:manage scope — tingnan ang Kunin ang iyong Ody API key.
• Ang iyong endpoint ay dapat isang HTTPS URL na mabilis na tumutugon na may 2xx status (nagta-time out ang mga paghahatid pagkatapos ng 10 segundo).
• Ang bawat workspace ay maaaring magrehistro ng hanggang 50 endpoint.

Hakbang-hakbang

1. Ilista ang mga uri ng event na maaari mong i-subscribe:

curl https://api.ody.co/v1/api/webhook-events \
  -H "Authorization: Bearer ody_live_…"

Ang catalog ngayon: message.received, message.delivered, message.failed, call.ringing, call.answered, call.completed, call.forwarded, call.missed, call.recording.completed, call.summary.completed, call.transcript.completed, call.voicemail.completed, call.flow.started, call.flow.completed, call.flow.aborted, contact.updated, contact.deleted. Ang pag-subscribe sa "*" ay sumasaklaw sa bawat kasalukuyan at hinaharap na uri ng event.

Ang mga call.flow.* event ay nagaganap kapag ang isang tawag ay sinagot ng isang call flow: started kapag pumasok ang tumatawag sa flow, completed kapag nakarating sila sa isang destinasyon (na may uri ng destinasyon — ring, AI assistant, voicemail, forward, o hangup), at aborted kung hindi natapos ang flow.

2. Irehistro ang iyong endpoint:

curl https://api.ody.co/v1/api/webhooks \
  -H "Authorization: Bearer ody_live_…" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/ody-webhook","events":["message.received"],"label":"prod"}'

3. Agad na i-store ang secret mula sa tugon. Ang whsec_… signing secret ay ibinabalik lamang sa paggawa at pag-rotate — hindi na ito muling ipapakita.
4. Magpadala sa iyong sarili ng nilagdaang test event at kumpirmahin na na-verify at tinatanggap ito ng iyong endpoint:

curl -X POST https://api.ody.co/v1/api/webhooks/WEBHOOK_ID/test \
  -H "Authorization: Bearer ody_live_…"

Ang test ay nagpo-post ng {"type":"ping"} event na nilagdaan nang eksakto tulad ng isang tunay na paghahatid.

Ano ang hitsura ng isang paghahatid

Ang bawat paghahatid ay isang POST na may JSON body at tatlong signature header:

{
  "id": "evt_…",
  "apiVersion": "2026-06-01",
  "createdAt": "2026-08-16T12:00:00.000Z",
  "type": "message.received",
  "data": { "conversationId": "…", "activityId": "…", "numberE164": "+1…" }
}

Header	Kahulugan
webhook-id	Ang event id — i-deduplicate dito, dahil ginagamit itong muli sa mga pagsubok ulit
webhook-timestamp	Unix seconds sa oras ng pagpapadala
webhook-signature	v1,<base64 HMAC-SHA256> sa <id>.<timestamp>.<raw body>

Pag-verify ng lagda

Ang HMAC key ay ang base64-decoded na bahagi ng iyong secret pagkatapos ng whsec_ prefix, at ang nilagdaang mensahe ay <webhook-id>.<webhook-timestamp>.<raw body>. Palaging i-verify laban sa raw request bytes — ang muling pag-serialize ng na-parse na JSON ay sumisira sa lagda. Tanggihan ang mga timestamp na mas matanda sa ilang minuto upang harangan ang mga replay.

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

const app = express();
app.post("/ody-webhook", express.raw({ type: "application/json" }), (req, res) => {
  const secret = process.env.ODY_WEBHOOK_SECRET; // whsec_…
  const id = req.headers["webhook-id"];
  const timestamp = req.headers["webhook-timestamp"];
  const signature = req.headers["webhook-signature"];

  // Replay guard: reject deliveries older than 5 minutes.
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return res.status(401).end();

  const key = Buffer.from(secret.slice("whsec_".length), "base64");
  const expected = "v1," + createHmac("sha256", key)
    .update(`${id}.${timestamp}.${req.body}`)
    .digest("base64");

  const a = Buffer.from(expected);
  const b = Buffer.from(String(signature));
  if (a.length !== b.length || !timingSafeEqual(a, b)) return res.status(401).end();

  const event = JSON.parse(req.body.toString("utf8"));
  console.log("verified event:", event.type);
  res.status(200).end();
});

Ang mga opisyal na SDK ay nagpapadala nito bilang isang one-liner — verifyWebhookSignature (TypeScript) at verify_webhook_signature (Python), parehong may constant-time comparison at ang 5-minutong replay guard na built in. Tingnan ang SDK quickstart: TypeScript at Python.

Mga pagsubok ulit, kasaysayan, at pamamahala

• Mga pagsubok ulit: ang isang nabigong paghahatid (non-2xx, timeout, o error sa koneksyon) ay sinusubukan ulit humigit-kumulang 5 segundo at pagkatapos ay 30 segundo pagkatapos ng unang pagsubok — tatlong pagsubok sa kabuuan, 10-segundong timeout bawat isa.
• Kasaysayan: Inililista ng GET /v1/api/webhooks/:id/deliveries ang mga kamakailang paghahatid na pinakabago muna, na may mga status code, error, at tagal sa bawat pagsubok — ang iyong unang hihintuan kapag tila nawawala ang mga event.
• Pamahalaan ang mga endpoint: Inililista ng GET /v1/api/webhooks ang mga ito (hindi kailanman ang secret), ina-update ng PATCH /v1/api/webhooks/:id ang url, events, label, o status (enabled/disabled), at inaalis ng DELETE /v1/api/webhooks/:id ang isa kasama ang kasaysayan ng paghahatid nito.
• I-rotate ang secret anumang oras gamit ang POST /v1/api/webhooks/:id/rotate — ang bagong whsec_… ay ibinabalik nang isang beses, at ang mga lumang lagda ay agad na humihinto sa pagiging balido.

Pag-troubleshoot

• Palaging nabibigo ang pag-verify ng lagda — malamang na nagve-verify ka ng isang re-serialized na body. Gamitin ang raw request bytes, at kumpirmahin na na-base64-decode mo ang secret pagkatapos tanggalin ang whsec_.
• Walang dumarating na paghahatid — tingnan kung ang status ng endpoint ay enabled, kasama sa listahan ng events nito ang uri na iyong inaasahan (o "*"), at ang kasaysayan ng paghahatid para sa mga error sa bawat pagsubok.
• Mga duplicate na event — ginagamit muli ng mga pagsubok ulit ang parehong webhook-id. I-deduplicate dito.
• naabot ang limitasyon ng webhook — nasa 50 endpoint ka na para sa workspace; tanggalin muna ang isang hindi ginagamit.

Mga kaugnay na artikulo

• Pangkalahatang-ideya at authentication ng API
• SDK quickstart: TypeScript at Python
• Mga limitasyon ng rate ng API at pinakamahusay na kasanayan