# Webhook Integration
Webhook is a mechanism based on HTTP push API for communicating from 1UPVISION to client service automatically when some event happens in our system.

## Description
It's is a way for an app to provide other applications with real-time information when some event happens in our system. A webhook delivers data to other applications as it happens, meaning you get data immediately. Unlike typical APIs where you would need to poll for data very frequently in order to get it real-time. This makes webhooks much more efficient for both provider and consumer.

## Webhook Setup
The first step in settiing up a webhook is specifiying a URL to deliver requests to. This is done through a backend panel or an API. This means that client also need to set up a URL in their service that’s accessible from the public web. This endpoint should support POST http method and expect a JSON formatted payload in request body.

Using the Webhooks API requires the following:
* You need to specify a URL to send those notifications and types of events you want to subscribed.
* You must deploy a publicly available and secure (HTTPS) endpoint for that URL that can handle the webhook payloads specified in this documentation.

## Event Types
Following are the event types, 1UPVISION product support for various modules.

### Core module
* Person Create (`people.create`)
* Person Update (`people.update`)
* Person Delete (`people.delete`)
* Person Bulk Create (`people.bulk_create`)
* Person Bulk Update (`people.bulk_update`)
* Person Bulk Delete (`people.bulk_delete`)

### 1UPAMS module
* Punch Create (`punch.create`)
* Punch Update (`punch.update`)
* Attendance Create (`attendance.create`)
* Attendance Update (`attendance.update`)

### 1UPVMS module
* Visit Checkin (`visit.checkin`)
* Visit Checkout (`visit.checkout`)
* Visit Update (`visit.update`)

## Security
In each webhook api call, we also sent some request headers like these

X-ServiceHook-Event: punch.create
X-ServiceHook-Timestamp: 2020-08-20T10:00:00Z
X-ServiceHook-UUID: 1dc54786-9d69-487a-8c17-407ff20d0bdc
X-ServiceHook-Signature: bb723bf0b05188e2f0a5f587ef107794e383e5029198e552d5fafdc5faf77243 

1. `X-ServiceHook-Event` - An webhook event type
1. `X-ServiceHook-Timestamp` - A timestamp when this request called
1. `X-ServiceHook-UUID` - A unique id of webhook integration for each organization
1. `X-ServiceHook-Signature` - A HMAC-SHA256 digest hash as signature of request body

We are using [HMAC](https://en.wikipedia.org/wiki/HMAC)-SHA256 algorithm to create digest of request body.
Example, Assume we want to create signature for above given sample `punch.create` webhook request payload. We will take focus on request body.

# Python 3.6+
import json
import hmac
from hashlib import sha256

# we will provide this secret key, unique for each organization. Keep this secret
SECRET_KEY = "WEBHOOK SECRET"

request_body = 'REQUEST BODY IS HERE'

signature = hmac.new(
            key=SECRET_KEY.encode("utf-8"),
            msg=request_data.encode("utf-8"),
            digestmod=sha256,
        ).hexdigest()

Then above calculated `signature` in code snippet should be equal to the `X-ServiceHook-Signature` custom request header value. If siganture doesn't match, consider request body as inauthentic.

## Retries
If your service has problems handling notifications at any time, 1UPVISION will attempt to re-send failed notifications up to 4 times.

1UPVISION will retry in the following cases:
* Connection failed: 1UPVISION cannot open an HTTP connection to the provided webhook URL.
* Timeout: your service takes longer than 30 seconds to send back a response to notification.
* Error codes: your service responds with any HTTP status code (4xx or 5xx).

## Example
Assume, you have provided following url as webhook url : `http://example.com/some-webhook-handler` and subscribed for `punch.create` event. 1UPVISION will call webhook url as POST http method with payload in request body.

**Request**

POST /some-webhook-handler

Host: example.com
Content-Type: application/json
X-ServiceHook-Event: punch.create
X-ServiceHook-Timestamp: 2022-08-28T17:36:59Z
X-ServiceHook-UUID: 1dc54786-9d69-487a-8c17-407ff20d0bdc
X-ServiceHook-Signature: bb723bf0b05188e2f0a5f587ef107794e383e5029198e552d5fafdc5faf77243 

{"punch":{"id":2,"punched_at":"2022-08-28T17:36:59.163781Z","punch_type":"IN","photo_url":"","body_temp":null,"body_temp_unit":null,"body_temp_status":null,"person":{"id":1,"first_name":"Rohit","last_name":"","mobile_number":"[phone]","email":"","dob":null,"primary_face_image_url":"","picture_url":null,"people_custom_data":{"data":[],"form_schema_revision_id":1},"people_form_schema_revision_id":1,"is_blacklisted":false,"created_at":"2023-06-14T06:23:40.675961Z"},"shift":{"id":1,"name":"Flexible Shift","code":"flexible-shift","type":"FLEXIBLE","created_at":"2022-02-02T12:12:09.798381Z","updated_at":"2022-02-02T12:12:09.798398Z"},"attendance":{"id":1,"attendance_date":"2022-08-28","shift_id":1,"person_id":1,"created_at":"2022-08-28T04:06:37.512632Z","updated_at":"2022-08-28T17:36:59.683209Z"},"created_at":"2022-08-28T17:36:59.540351Z","updated_at":"2022-08-28T17:36:59.540375Z","space_id":1,"organization_id":1}}

**Response**

200 OK