CONNECT WEBHOOK

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

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

- Screen for create application.

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

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

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

3. Step 3: Register webhook

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

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

- 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) withverify_token (in your app).

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

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

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

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

4. 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).
  • Scope:
    • https://docs.haravan.com/blogs/omni/tutorial-use-scope
  • Access_token:
    • https://docs.haravan.com/blogs/omni/create-app-and-connect-api
    • https://www.youtube.com/watch?v=gzJ0_qbrvYM&feature=youtu.be

- 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

4.3. Use 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

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

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.

• Next, get X-Haravan-Hmacsha256

• 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

• 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).
  • Scope https://docs.haravan.com/blogs/omni/tutorial-use-scope
  • Access_token:

    + https://docs.haravan.com/blogs/omni/create-app-and-connect-api

    + https://www.youtube.com/watch?v=gzJ0_qbrvYM&feature=youtu.be

- 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

7.3. Use Postman

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