CONNECT WEBHOOK
Docs version 2- You can register webhook to receive notifications about particular events in a shop.
- Note:
+ Notification contains a JSON payload.
+ Only support HTTPS.
- 1. Step 1: Create app
- 2. Step 2: Use ngrok to register webhook
- 3. Step 3: Register webhook
- 4. Step 4: Call api subscribe webhook
- 5. Step 5: Receive notifications from webhook
- 6. Step 6: Authenticate webhook
- 7. Step 7: Call api unsubscribe webhook
- 8. Note:
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).
- Do this step after you have access_token.
- The purpose is to declare that your application can receive webhook notifications.
4.1. Request
Method | URL |
POST | https://webhook.haravan.com/api/subscribe |
Header:
Content-Type: application/json
Authorization: Bearer + access_token
4.2. Response
Status | Response |
200 | { |
422 | {"error": "Unprocessable Entity"} |
401 | Unauthorized |
429 | Too many requests |
500 | Something went wrong. Please try again later. |
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).
- Do this step after you have access_token.
- The purpose is to stop receiving webhooks notifications.
7.1 Request
Method | URL |
DELETE | https://webhook.haravan.com/api/subscribe |
Header:
Content-Type: application/json
Authorization: Bearer + access_token
7.2. Response
Status | Response |
200 | { |
422 | {"error": "Unprocessable Entity"} |
401 | Unauthorized |
429 | Too many requests |
500 | Something went wrong. Please try again later. |
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.