Skip to main content

Connect webhook

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

connect-webhook-7

  • You need to fill in some information:
    • Callback URL: Webhooks will GET a message with query 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:
GET {YOUR_WEBHOOK_CALLBACK_URL}?hub.mode=subscribe&hub.verify_token={Verify_Token}&hub.challenge=bf54608bf2004fc2a528f9e69f774135
  • 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

Step 4: Call api subscribe webhook​

  • Note:

    • First, you need Haravan’s access_token to use Haravan’s Api.
    • You also need right scope to get Haravan’s access_token.
    • The scope to use webhook is: wh_api. (You need more scope for install and use orther api).

  • Do this step after you have access_token.

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

4.1. Request​

MethodURL
POSThttps://webhook.haravan.com/api/subscribe
Header:
   Content-Type: application/json
   Authorization: Bearer {Token}

Request body: {}

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​

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.

  • Collect 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 + Client 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('CLIENT_SECRET','your_app_client_secret');

function verify_webhook($data,$hmac_header)
{
$calculated_hmac = base64_encode(hash_hmac('sha256', $data, CLIENT_SECRET, true));
return ($hmac_header == $calculated_hmac);
}

//header "X-Haravan-Hmacsha256" in PHP become "HTTP_X_HARAVAN_HMACSHA256"
$hmac_header = $_SERVER['HTTP_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
?>

Example in Nodejs: https://github.com/Haravan/haravan-validate

Step 7: Call api unsubscribe webhook​

  • Note

    • First, you need Haravan’s access_token to use Haravan’s Api.
    • You also need right scope to get Haravan’s access_token.
    • The scope to use webhook is: wh_api. (You need more scope for install and use orther api).

  • Do this step after you have access_token.

  • The purpose is to stop receiving webhooks notifications.

7.1 Request​

MethodURL
DELETEhttps://webhook.haravan.com/api/subscribe
Header:
   Content-Type: application/json
   Authorization: Bearer {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 {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.