Overview

Webhooks let your system react to events on Bunjang in near real time, without polling. When something happens on Bunjang's side — such as an order's status changing — Bunjang sends an HTTP POST request to the endpoint you registered, carrying a JSON payload that describes the event.

This guide explains how Bunjang webhooks work, how to subscribe, and what your endpoint must do to handle them safely and reliably.

Key concepts

Event — A discrete change that occurred on Bunjang (for example, an order item moving from PAYMENT_RECEIVED to SHIPPED). Each event is uniquely identified by an eventId.

Payload — The event-specific data contained in the data field of the webhook request body. The payload structure varies depending on the eventType.

Envelope — The common metadata section of the webhook request body, consisting of eventId, eventType, and payloadVersion.

Signature — An HMAC-SHA256 value in the X-Bun-Webhook-Signature header that proves the request originated from Bunjang and was not tampered with.

Idempotency — The practice of safely handling duplicate deliveries of the same event by deduplicating on eventId.

Circuit breaker — A protection mechanism that automatically suspends delivery to your endpoint after repeated failures, with periodic recovery attempts.

How webhooks work

An event occurs on Bunjang (for example, an order's status changes).

Bunjang sends an HTTP POST request to your registered endpoint with the event payload.

Your endpoint verifies the signature, checks the eventId for duplicates, and quickly returns a 2xx response.

Your system processes the event asynchronously, typically by fetching the latest authoritative state from the Order API.

If your endpoint fails to respond with 2xx (e.g. 5xx, timeout, network error), Bunjang automatically retries based on the retry policy.

Design principle

Treat webhook delivery as a notification mechanism that reduces polling frequency, not as a guaranteed event stream. For business-critical state, the corresponding REST API is the source of truth, and webhooks are an optimization that lets you avoid constant polling under normal operating conditions.

For event types not yet covered by webhooks, periodic polling of the
corresponding REST API remains the appropriate pattern.

Getting started

1. Request a subscription

Send an email to partner_global@bunjang.co.kr with the following information:

Item	Description	Example
Endpoint URL	The HTTPS URL that will receive webhook requests	`https://api.partner.com/webhooks/bunjang`
Subscribed events	The list of event types you want to receive	`order.status.changed`

Coming in Q3 2026: The Partner Center will allow you to register endpoints, issue signing secrets, and manage subscriptions directly through a self-service dashboard, removing the need for email-based onboarding.

2. Receive your signing secret

After your subscription is approved, Bunjang will provide:

Signing secret — A secret key used to verify the authenticity of webhook requests. Store this in a secrets manager and never commit it to source control.

Important: The signing secret is shown only once at issuance. If lost, you must request a new secret, which invalidates the previous one.

3. Implement your endpoint

Your endpoint must, at a minimum:

Accept POST requests with Content-Type: application/json.

Verify the X-Bun-Webhook-Signature header using your signing secret. See Signature Verification for details.

Deduplicate events by eventId. See Retry & Idempotency for details.

Return a 2xx HTTP status code as quickly as possible — heavy processing should happen asynchronously, after the response is sent.

4. Test and go live

Once your endpoint is implemented, coordinate with your Bunjang integration contact to enable delivery in production.

Supported events

Event type	Description	Payload version
`order.status.changed`	Triggered when the status of an order item changes.	`v1`

Additional event types will be added over time. Each event type carries a payloadVersion field; consult the corresponding event reference page for the data schema of each version.

Endpoint requirements

Your webhook receiver must meet the following requirements:

HTTPS only — HTTP endpoints are not accepted. TLS 1.2 or higher is required.

Verify every request — Reject any request with a missing or invalid signature.

Implement idempotency — Process each eventId exactly once, even if delivered multiple times.

Respond quickly — Return 2xx within the response timeout. Defer non-trivial work to an asynchronous worker.

Treat the payload as a notification, not authoritative state — The data field reflects the state at the moment the event was emitted. For business decisions, fetch the latest state from the corresponding REST API (for example, the Order API).

Reference

Signature Verification — How to validate the X-Bun-Webhook-Signature header, with code examples in Node.js, Kotlin, and Python.

Retry & Idempotency — Retry policy, circuit breaker behavior, and how to safely handle duplicate deliveries.

Events — Detailed schema and example payload for each supported event type.

Key concepts#

How webhooks work#

Design principle#

Getting started#

1. Request a subscription#

2. Receive your signing secret#

3. Implement your endpoint#

4. Test and go live#

Supported events#

Endpoint requirements#

Reference#