Skip to content

Webhooks

In this guide, we will look at how to register and consume webhooks to integrate your app with Protocol. With webhooks, your app can know when something happens in Protocol, such as someone sending a message or adding a contact.

Integration Guide

Introduction

Webhooks provide an efficient way for your system to receive real-time notifications about payment-related events from our platform. This includes scenarios when an order is placed and when a refund occurs.

Webhook Trigger Points

Currently, there are two specific points in time when webhooks are triggered:

  • Payment Success: A webhook is sent when an payment is successfully paid.
  • Refund Success: A webhook is sent when an payment is successfully refunded.

Consuming Data

When your app receives a webhook request from Protocol, check the type attribute to see what event caused it. The first part of the event type will tell you the payload type, e.g., a conversation, message, etc.

Payment Data Structure When a payment event occurs, our system will send JSON data in the following format to your configured endpoint:

Payment Data Structure
{
"user": {
"id": "00f7407f-219e-4ada-9390-28934d7398d5",
"email": "demo@kaik.io",
"name": "Kaik",
"phone_number": "+886911222333",
"third_party_id": "123123"
},
"trade_no": "DEM2022053167602AF30",
"currency": "TWD",
"amount": "3488.0",
"paid_at": "2022-05-31 11:28:31 +0800",
"created_at": "2022-05-31 11:26:42 +0800",
"refunded_at": null,
"payment_state": "paid",
"payment_type": "credit",
"affiliate_code": "newswebPAGE7",
"remark": "Order note",
"lineitems": [
{
"name": "Course Name 123",
"quantity": 1,
"amount": "3488.0",
"item_type": "CurriculumPlan",
"item_id": "51e07cb8-e450-4ed4-8b54-e0144d4da793",
"item_slug": "test-slug"
},
{
"name": "Course Name",
"quantity": 1,
"amount": "3488.0",
"item_type": "CurriculumPlan",
"item_id": "51e07cb8-e450-4ed4-8b54-e0144d4da793",
"item_slug": "test-slug"
}
],
"coupon": null,
"shipping_address": {
"city": "Taipei",
"district": "Songshan District",
"postal_code": "105065",
"address": "xxxxx",
"full_address": "105065 Taipei City, Songshan District, xxx"
},
"invoice": {
"number": "BL90912974",
"buyer_ubn": null,
"buyer_name": "Kaik Demo",
"category": "b2c"
},
"custom_data": [
{
"field_id": "xxxxxx",
"label": "Field One Name",
"type": "multi_select",
"values": ["A", "B"],
"position": 0
},
{
"field_id": "xxxxxx",
"label": "Field Two Name",
"type": "radio",
"values": ["1"],
"position": 1
},
{
"field_id": "xxxxxx",
"label": "Field Three Name",
"type": "text",
"values": ["xxxxx"],
"position": 2
}
]
}

Handling Webhooks

Once your endpoint receives a webhook request, you should:

  1. Validate the Request: Ensure the request is from a trusted source.
  2. Parse the Data: Decode the JSON data and process it according to your business logic. For example, updating order status or recording transaction details.
  3. Respond to the Request: Respond to the webhook request. Typically, a HTTP status code 200 indicates successful receipt.