Webhooks

A webhook is a URL that can be used as a callback to receive information when an event is triggered within the UnivaPay platform. Payloads for a webhook are delivered via a POST request. The body of the request will contain a JSON object with relevant data resource. Webhooks can be created via the merchant console (see Guide).

The following table displays all events you can register a webhook, their payload resource model, and a short description of the triggering event.

Event name	Resource type	Info
`charge_updated`	charge	A charge is updated (`authorized`, `awaiting`)
`charge_finished`	charge	A charge is finalized (`canceled`, `error`, `failed`, `successful`)
`subscription_payment`	subscription	A payment is received for a subscription
`subscription_completed`	subscription	A subscription has been completed
`subscription_failure`	subscription	A payment failed to complete for a subscription
`subscription_canceled`	subscription	A subscription has been canceled
`subscription_suspended`	subscription	A subscription has been suspended
`subscription_created`	subscription	A subscription has been created
`token_created`	token	A transaction token has been created
`token_updated`	token	A transaction token has been updated
`token_cvv_auth_updated`	token	A transaction token `data.cvv_authorized.status` has been updated
`recurring_token_deleted`	token	A recurring token has been deleted
`token_replased`	token	A recurring token has been replased
`refund_finished`	refund	A refund is finished (success/failure)
`cancel_finished`	cancel	A cancel is has been finalized and received
`customs_declaration_finished`	customs declaration	A customs declaration has been finalized

{
  "event": "charge_finished",
  "data": {
    "id": "11e8d04b-5143-f59c-9fa3-e81a25b8537d",
    "store_id": "11e8707d-f289-db48-9d47-dee2fc997783",
    "transaction_token_id": "11e8d04b-5129-9120-9fa1-45a9442661a0",
    "transaction_token_type": "one_time",
    "subscription_id": null,
    "requested_amount": 1500,
    "requested_currency": "JPY",
    "requested_amount_formatted": 1500,
    "charged_amount": 1500,
    "charged_currency": "JPY",
    "charged_amount_formatted": 1500,
    "only_direct_currency": false,
    "capture_at": null,
    "descriptor": null,
    "status": "successful",
    "error": null,
    "metadata": {
      "customer_name": "Carl Ferguson",
      "memo": "MID-12345678",
      "gpapps_contract_id": "98013bca-5fad-4076-85ff-0b5c87f39165"
    },
    "mode": "test",
    "created_on": "2018-10-15T07:24:13.933088Z"
  }
}

{
  "event": "refund_finished",
  "data": {
    "id": "11e8d04c-76ac-f3a0-9fbc-5600743c02b7",
    "store_id": "11e8707d-f289-db48-9d47-b1122dd49d32",
    "charge_id": "11e8d04c-1591-d89c-9fb6-d773e56d5320",
    "status": "failed",
    "amount": 1200,
    "currency": "JPY",
    "amount_formatted": 1200,
    "reason": "customer_request",
    "message": "Test refunds",
    "error": {
      "code": 309,
      "message": "Test refund failed purposely",
      "details": "Test refund failed purposely"
    },
    "metadata": {},
    "mode": "test",
    "created_on": "2018-10-15T07:32:26.193631Z"
  }
}

{
  "event": "customs_declaration_finished",
  "data": {
    "id": "24c6c41f-93bd-4469-ada3-f4819be8b4f8",
    "charge_id": "11ec053a-52b5-8464-bb85-d76d3bef56e9",
    "merchant_id": "11ec053a-5252-2cde-bb85-f3646674285f",
    "store_id": "11ec053a-5275-cba8-bb85-ffc3cc0b6f21",
    "mode": "live_test",
    "gateway": "we_chat_online",
    "declaration": {
      "customs": "HANGZHOU_ZS",
      "merchant_customs_no": "123456",
      "certificate_id": "certificateIdTest",
      "certificate_name": "certificateNameTest"
    },
    "declaration_result": {
      "trade_id": "2018112288340107038204310100000",
      "approving_authority": "UNIONPAY"
    },
    "status": "successful",
    "error": null,
    "created_on": "2021-08-25T09:21:00.052073+09:00"
  }
}

{
  "event": "customs_declaration_finished",
  "data": {
    "id": "bdb058f3-1231-4817-8c00-a9bf37d07bfe",
    "charge_id": "11ec053c-a2f0-8d82-a653-07800a68253f",
    "merchant_id": "11ec053c-a28f-3190-a653-6702fd115e11",
    "store_id": "11ec053c-a2ae-d6b2-a653-2fdb82d75fa5",
    "mode": "live_test",
    "gateway": "we_chat_online",
    "declaration": {
      "customs": "HANGZHOU_ZS",
      "merchant_customs_no": "123456",
      "certificate_id": "certificateIdTest",
      "certificate_name": "certificateNameTest"
    },
    "declaration_result": {
      "trade_id": "2018112288340107038204310100000",
      "approving_authority": "UNIONPAY"
    },
    "status": "failed",
    "error": {
      "code": 304,
      "message": "Identity information is not matched"
    },
    "created_on": "2021-08-25T09:37:33.618921+09:00"
  }
}

Webhook object

The following table describes the webhook object model when creating the webhook. Please take note that this is not the model that is sent to the webhook, but the configuration object when describing the webhook.

Webhooks can be linked to a merchant or a store. Merchant linked webhooks are triggered events occuring on all stores while store linked webhooks are triggered only for that specific store and are denoted by the presence of the store_id field.

Fields
id	UUID The UUID to identify the webhook.
merchant_id	UUID The UUID of the merchant that the webhook belongs to
store_id	UUID The UUID of the store that the webhook belongs to
triggers	array[string] A list of events that will trigger this webhook to fire a request
url	string The URL of the endpoint to send the webhook request to
auth_token	string An optional `authorization` header value to include when sending the webhook request
active	boolean Whether the webhook is enabled
created_on	string (ISO-8601) The date the webhook was created on