Webhook Format
Webhooks conform to a standard format.
Webhooks in the Payment API have a two-layer structure:
The outer layer, or wrapper layer, containing basic information about the webhook.
The
data
object inside thebody
object, containing the specific information generated by the trigger event.
In some cases, the data is an entire data object, such as a payment or an identity verification inquiry.
This page describes the wrapper layer in Payment API webhooks. For details about the data
section, see each individual webhook.
Webhooks in the Point-of-Sale (POS) API have a one-layer structure that is unique to each webhook.
Request URL
Webhooks are sent to a URL that is designated by the merchant. See Defining a Webhook Endpoint
Root-Level Parameters
The root level of the JSON message contains the following fields:
Parameter | Type | Description |
---|---|---|
method | string | post |
json | Boolean | true |
headers | object | See Webhook Format. |
uri | string | The URI of the webhook endpoint set by the client. See Defining a Webhook Endpoint. |
body | object | See Webhook Format. |
timeout | number | Internal. |
resolveWithFullResponse | Boolean | Internal. |
Header Parameters
The headers
object contains the following fields:
Parameter | Type | Description |
---|---|---|
'Content-Type' | string | application/json |
timestamp | string | Time that the webhook was sent, in Unix time, integer as string. |
salt | string | Random string for each request. Digits, letters and special characters. |
signature | string | An encrypted string. See Webhook Authentication. |
Body Parameters
The body
object contains the following fields:
Parameter | Type | Description |
---|---|---|
id | string | ID of the webhook. String starting with wh_. |
type | string | Name of the webhook type. Note: The name in the Client Portal is different. |
data | object | Contains the actual data of the webhook. For details, see each individual webhook. |
trigger_operation_id | string | ID of the operation that triggered the webhook. UUID. |
status | string | Status of the webhook. One of the following:
Note: Inside the |
created_at | string | Time that the webhook was created, in Unix time. Note: Inside the |
Example Webhook
{ method: 'POST', json: true, headers: { 'Content-Type': 'application/json', timestamp: '1575812352', salt: 'Oac/iU3wivthSAIvTJdE/A==', signature: 'Mjc0MmM5YzQ3MDk0OWUwNGQ1Yjg4OTFkMTQ1zMTYzZTYxOWVhMjUyNjcyYThiMjFlYmJhMjYNzcwYmMzOWFmZg==' }, uri: 'http://webhook-endpoint.example-client.io', body: { id: 'wh_81a54cf977b0b6b3ee57d870e2d6ec4a', type: 'CUSTOMER_PAYMENT_METHOD_CREATED', data: { id: 'other_f0fcb1feb6f38434cdb3e697e6158cfa', type: 'kr_happymoney_ewallet', image: '', category: 'ewallet', metadata: {} }, trigger_operation_id: '0fd3bdc9-de75-4768-bc12-b807582b069c', status: 'NEW', created_at: 1575812351 }, timeout: 15000, resolveWithFullResponse: true }