• You can register webhook to receive notifications about particular events in a shop.
  • Note:
    • Notification contains a JSON payload.
    • Only support HTTPS.


TABLE OF CONTENTS

1. Step 1: Create app

- Follow the link https://developers.haravan.com/apps (If you haven’t logged in, the system will redirect to sign in https://accounts.haravan.com, and at this page you can sign in or sign up).

Tạo App

- After sign in/sign up successful, the system will show a list of your applications, click "Create App" button to create a new application.

Tạo App

- Screen for create application.

Giao diện tạo mới ứng dụng

  • Name: application name.
  • Description: application description.
  • Redirect Url: application domain, the system will redirect to this url when starting application.

- Create success.

+ Some field need to save in config file to use: App Id, App Secret, Redirect Url.

Tạo ứng dụng thành công.

- After created, your application will be appeared on list https://developers.haravan.com/apps

Sau khi tạo thành công

2. Step 2: Use ngrok to register webhook

- Ngrok (https://ngrok.com/) creates a secure tunnel on your local machine along with a public
URL you can use for browsing your local site.

- If you’re running your local web server on port 3000, in terminal, you’d type in: ngrok http 3000.

- Note:

  • A url can be available for 8 hours
  • Only use https://
  • Use ngrok's web inspection interface to understand the HTTP request and response traffic over your tunnel: http://localhost:4040

Tạo ngrok để đăng kí webhook

3. Step 3: Register webhook

- Choose “Webhooks” on the sidebar, click “Register” button

Cấu hình webhook

- You need to fill in some information:

  • Callback URL: Webhooks will POST a message with data to this URL when certain things happen. Make sure the url is configured on your application to receive webhooks.
  • Verify Token: is random string and has at least 1 character, because it’s used for authenticating with an app, make sure this token matches the string configured on your app.

Nhập vào Verify Token

- When you submit, the system will call to your app via the Callback URL

- When callback to your app, the system will send an object to verify.

{
  "hub.mode": "subscribe",
  "hub.verify_token": "YiquHMHXpfRMkgNTUc60kFaLLKYpDGR9",
  "hub.challenge": "23236cb70fe64c1ebcf047574a41eb14"
}

- You need to compare hub.verify_token (in object) with verify_token (in your app).

  • If not match, response status 401.
  • If match, response status 200 and value of hub.challenge

Đăng kí webhook

- After registered, you need to reload this page to see the list of events that can subscribe to get notifications.

Đăng kí thành công

- Use ngrok's web inspection interface to understand the HTTP request and response traffic over your tunnel: http://localhost:4040

 Webhook register

- The purpose is to subscribe which events your app want receive notifications.

4. Step 4: Call api subscribe webhook

- Note:

- Do this step after you have access_token.

- The purpose is to declare that your application can receive webhook notifications.

4.1. Request

Header:
   Content-Type: application/json
   Authorization: Bearer + access_token 

4.2. Response

Status

Response

200

{
"error": false,
"message": "Đăng ký webhook thành công."
}

422

{"error": "Unprocessable Entity"}

401

Unauthorized

429

Too many requests

500

Something went wrong. Please try again later.

4.3. Use Postman

Sử dụng Postman

5. Step 5: Receive notifications from webhook

- After completing the above steps, webhooks will send request to notify your application with method POST.

- When sending notify, the webhook will include data in the request, but first you need to pay attention to:

  • org_id : to know which shop
  • topic: to know which notifications for which events.

- For example, we register an account update event

Receive notifications from webhook

- When you update your account at https://accounts.haravan.com/, webhook will notify your application with the topic is "user / update" and data of your account via CallBack URL.

Receive notifications from webhook

 Webhook thường

6. Step 6: Authenticate webhook

- When you receive data from webhook, you need to verify that it’s data sent from the system.

  • Choose “Settings” on the sidebar, copy App secret.

Authenticate webhook

  • Next, get X-Haravan-Hmacsha256

Authenticate webhook

  • To authenticate the webook:
    • First, we use hash_mac function with “sha256” algorithms to encode a string (data in webhook request + App Secret) to get the hash code.
    • Second, use base64 function to encode this hash.
    • Finally, compare it with X-Haravan-Hmacsha256(header of webhook request)..
      • If not matches, response status 401.
      • If matches, response status 200.
Example in PHP:

<?php
define('Haravan_APP_SECRET','my_shared_secret');

function verify_webhook($data,$hmac_header) { $calculated_hmac = base64_encode(hash_hmac('sha256', $data, Haravan_APP_SECRET, true)); return ($hmac_header == $calculated_hmac); }
$hmac_header = $_SERVER['X-Haravan-Hmacsha256']; $data = file_get_contents('php://input'); $verified = verify_webhook($data, $hmac_header); error_log('Webhook verified:'.var_export($verified, true)); //check error.log to see the result ?>

7. Call api unsubscribe webhook

- Note

- Do this step after you have access_token.

- The purpose is to stop receiving webhooks notifications.

7.1 Request

Header:
   Content-Type: application/json
   Authorization: Bearer + access_token 

7.2. Response

Status

Response

200

{
"error": false,
"message": "Xóa webhook thành công.",
"error_Code": null
}

422

{"error": "Unprocessable Entity"}

401

Unauthorized

429

Too many requests

500

Something went wrong. Please try again later.

7.3. Use Postman

Use Postman

8. Call api get subscribed webhook

8.1 Request

Header:
   Content-Type: application/json
   Authorization: Bearer + access_token 

8.2. Response

Status

Response

200

{
  "data": [
     {  
       "id": "612849678226d51c00dcade4",
       "event": "app/uninstalled",
     },{ 
       "id": "612849678226d51c00dcade2",
       "event": "products/update",
     },{
       "id": "612849678226d51c00dcaddd",
       "event": "shop/update",
  }],
  "error": false,
  "message": "Thành công.",
  "error_Code": null
}

422

{"error": "Unprocessable Entity"}

401

Unauthorized

429

Too many requests

500

Something went wrong. Please try again later.

9. Note

- If you do not response status 200 when you received a notification from the webhook, the system will automatically send again.

- Remove ngrok if not used anymore to avoid system spam.

- When uninstall your application, it will lose subscribers, you need to call api subscriber like step 4 again to subscriber the webhook for your application every time you reinstall the app.

Retry frequency:

Your webhook acknowledges that it received data by sending a 200 OK response. Any response outside of the 200 range, including 3XX HTTP redirection codes, indicates that you didn't receive the webhook.

Haravan doesn't follow redirects for webhook notifications and considers them to be an error response.

Haravan has implemented a five-second timeout period and a retry period for webhook subscriptions.

Haravan waits five seconds for a response to each request to a webhook. If there's no response, or an error is returned, then Haravan retries the connection 19 times over the next 48 hours. If there are 19 consecutive failures, then the webhook subscription is automatically deleted. A warning that the subscription will be deleted is sent to the app's emergency developer email address.

To avoid timeouts and errors, consider deferring app processing until after the webhook response has been successfully sent.