Inbound Webhook Configuration

Inbound delivery is not REST polling — the Gateway pushes events to your webhook. This is called bypass mode: events fan out directly to your server without passing through the Kakao inbound server or a human-agent console.

How it works

Configuration steps

Every step happens in TalkBridge Center under Integrations → Developer mode. The setup steps indicator at the top of the screen tells you what to do next.

1. Finish channel verification — Developer mode starts from a brand whose Kakao channel has been verified in Brand settings.
2. Issue an integration key — Click Issue integration key in the "Integration key" card and all three values are ready at once. Copy all as .env copies them together with the API address.
   • Brand Key — The brandKey of API requests and the CLI --channel value. It equals brand in inbound signals.
   • Agent Key (blumnb-…) — Authenticates API calls (Authorization: Bearer). The plaintext is shown only once, right after issuance.
   • Signature verification key (whsec_…) — Verifies the signature of inbound webhooks.
3. Prepare your inbound server — Configure the signature verification key on your inbound server and implement the handling in the table below.
4. Connect the webhook URL — Register your inbound URL (HTTPS) in the Custom service row.
5. Run the connection tests — The "Connection test" card checks two things. Nothing is sent to real customers.
   • Inbound test — Sends a test signal to your webhook URL with the same headers and signature as a real delivery, and shows the response code and its likely cause (see Test signal).
   • Outbound readiness test — Paste the Agent Key plaintext and it actually calls authentication (GET /api/agent/me) → brand permission → conversation history (GET /api/agent/rooms), then tells you whether the key can send (brand-write). The key you enter is not stored.
6. Turn on consultations — Turn on Consultation at the top of the screen and inbound events for that brand begin to be delivered to your URL. Delivery results appear under Recent deliveries in the "Connection test" card.

Signature verification key = derived from the connected integration key

The hosted Gateway does not issue a separate signing secret. The signature verification key is deterministically derived from the integration key connected to the Gateway and shown in TalkBridge Center (recomputable — not show-once). If you issue a new integration key, the signature verification key changes too, so update the value on your inbound server as well. The previous key is not revoked automatically. (The CLI Gateway takes it directly via --webhook-secret — see CLI Gateway.)

Additional keys

Personal keys for the CLI or other servers, and read-only (brand-read) keys, are created under Issue additional key in the "Integration key" card. These keys are not connected to the Gateway, so the signature verification key does not change.

What your webhook server must do

Step	Document
1. Receive the request and verify the signature	Signature Verification
2. Branch on the event using the payload's kind	Inbound payload
3. Fetch the content when needed (rooms API)	Content Retrieval
4. Return a 2xx response (otherwise it is retried)	Delivery Reliability
5. Reply through the outbound API	Outbound API

Inbound server security checklist

Your webhook server is an endpoint open to the internet. Check the items below.

• Verify the signature and the timestamp together — X-Bridge-Signature stops forgery, and an allowed window on X-Bridge-Timestamp (for example ±5 minutes) stops replays. See Signature Verification.
• Verify against the raw bytes — If you parse the body as JSON and serialize it again, the signature no longer matches. Compute it over the bytes exactly as received.
• Keep the signature verification key in a secret store — Not in code, logs, or client (browser) code. Store it separately from the Agent Key, so a leak of one does not expose the other's permissions.
• Public HTTPS address — The Gateway does not follow private IPs or redirects. Register the final URL of your inbound server directly.
• When you download and keep attachments (SSRF) — Photos, videos, voice messages, and files that a customer sends with KakaoTalk's upload feature arrive in the body as a Kakao CDN URL (https://talk.kakaocdn.net/…), and that URL stops working after a while. To keep them, download them right after you receive them (Images · attachments). The points below apply only when your server downloads the URL itself (not when you just display the URL).
  • Before downloading, confirm exactly that the host is the Kakao CDN. The body can also be text the customer typed, so it may contain internal addresses such as http://169.254.169.254/… (cloud metadata). Parse the URL, compare the https scheme and the host exactly, and reject any URL that carries user info (the part before @).
  • Do not compare by string prefix. https://talk.kakaocdn.net@169.254.169.254/ starts with https://talk.kakaocdn.net, but the host actually contacted is the part after @.
  • For URLs that are not on the Kakao CDN (links the customer typed), do not download them — just show them as links. If you must fetch one, refuse hosts that resolve to private, loopback, or link-local addresses, do not follow redirects, and connect to the IP you checked (to prevent DNS rebinding).

HTTPS · public domain

The Gateway delivers only to public HTTPS URLs (private IPs and SSRF are blocked). For local development, obtain a public address through a tunnel (for example, Tailscale Funnel or ngrok).