---
title: "Register a webhook endpoint for booking lifecycle events"
method: POST
path: "/v1/webhooks"
tags: ["Webhooks"]
---

# Register a webhook endpoint for booking lifecycle events

`POST /v1/webhooks`

## Request

- Base URL: `https://api.gojinko.com`
- URL: `https://api.gojinko.com/v1/webhooks`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

Subscribe a callback URL to `booking.processing`, `booking.completed`, `booking.failed`, `booking.partial`, `servicing.completed`, `servicing.exchange_confirmed`, `servicing.ticket_issued`, or `servicing.failed`. The response includes the HMAC signing secret ONCE. Deliveries are signed with `X-Jinko-Signature: sha256=<hex>` over `"<X-Jinko-Timestamp>.<raw body>"`.

## Request body

- CreateWebhookRequest
  - `url` string, uri, required
  - `events` WebhookEvent[], required

## Response `201`

Webhook registered (secret shown once)

- WebhookCreatedResponse
  - `id` number, required
  - `url` string, required
  - `events` string[], required
  - `secret` string, required: HMAC signing secret. Returned ONCE — store it securely; later reads show only a prefix.
  - `status` string, required
  - `created_at` string, required

## Other responses

- `400`: Bad request
- `401`: Authentication required
- `402`: Payment required — organization balance exhausted
- `404`: Resource not found
- `409`: The operation conflicts with the current state of the resource
- `410`: The resource this request names no longer exists
- `422`: Validation error
- `429`: Rate limit or quota exceeded
- `502`: The travel provider rejected the request, or an upstream call failed
- `503`: No travel provider can serve the request right now
- `504`: The travel provider did not answer in time

---

[API](https://skmtc.dev/gojinko/apis/jinko-public-api.md) - [All operations](https://skmtc.dev/gojinko/apis/jinko-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/gojinko/apis/jinko-public-api/revisions/ac5046767e4c?raw)