Skip to main content

Connect webhook

Version 1.0.0

  • 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

Step 1: Create app

connect-webhook-1

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

connect-webhook-2

  • Screen for create application.

connect-webhook-3

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.

connect-webhook-4

connect-webhook-5

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

connect-webhook-6

Step 3: Register webhook

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

connect-webhook-7

  • 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.

connect-webhook-8

  • 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

connect-webhook-9

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

connect-webhook-10

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

connect-webhook-11

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

Step 4: Call api subscribe webhook

4.1. Request

MethodURL
POSThttps://webhook.haravan.com/api/subscribe
Header:
Content-Type: application/json
Authorization: Bearer + access_token

4.2. Response

Status Response
200
{
"error": false,
"message": "Xóa 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

connect-webhook-12

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

connect-webhook-13

  • 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.

connect-webhook-14

connect-webhook-15

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.

connect-webhook-16

  • Next, get X-Haravan-Hmacsha256

connect-webhook-17

  • 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
?>

Step 7: Call api unsubscribe webhook

7.1 Request

MethodURL
DELETEhttps://webhook.haravan.com/api/subscribe
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

connect-webhook-18

Step 8: Call api get subscribed webhook

8.1 Request

MethodURL
GEThttps://webhook.haravan.com/api/subscribe
Header:
Content-Type: application/json
Authorization: Bearer + access_token

8.2. Response

Status Response
200
{
"data":
[
{
"id": "612849678226d51c00dcade4",
"event": "app/uninstalled",
"url": "https://f9f0c2976796.ap.ngrok.io/webhooks"
},
{
"id": "612849678226d51c00dcade2",
"event": "products/update",
"url": "https://f9f0c2976796.ap.ngrok.io/webhooks"
},
{
"id": "612849678226d51c00dcaddd",
"event": "shop/update",
"url": "https://f9f0c2976796.ap.ngrok.io/webhooks"
}
],
"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.

Step 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.