Webhook

A webhook is a mechanism for one system to send data to another system as soon as a specific event occurs. It's a way to automate data exchange and communication between different software

WEBHOOK SUPPORT

1. Use the callback_url provided on a task request

   • Link:https://developer.cloudfactory.app/cloudfactory-public-api/reference/human-oversight-api/submit-task

2. Webhook Url Expectations:

   • POST request is supported on the webhook URL and the URL provides 200 as the response code for successful request

   • The webhook URL should not have any authentication in place

3. Retry mechanism:

   • On Webhook fall failure we will retry for 4 times Exponentially backing ( 1Hr, 2Hr, 4Hrs)) off until the 4th retry limit is reached.

4. Request to callback URL will Auto Timeout after 5 seconds \

WEBHOOK SECURITY HEADER

For enhanced security and data integrity, CloudFactory employs a robust authentication mechanism for all dispatched webhook events. This mechanism guarantees the authenticity and origin of received data, allowing clients to process information with confidence.

Verification Process:

1. Signature Generation: Each transmitted webhook event includes a unique signature. This signature is derived through a cryptographically secure hashing function (SHA-256) applied to the event payload utilizing a confidential key shared exclusively between CloudFactory and the client’s service.

2. Signature Transmission: The generated signature is appended to the HTTP request headers delivered to the client’s designated webhook URL, specifically within the "X-CF-Signature" header.

3. Signature Verification: Upon receiving a webhook event, it is imperative to independently compute a signature using the identical shared secret key and the received event payload.

4. Authentication Validation: The computed signature is compared against the received "CF-Signature" header value (v1). A successful match conclusively verifies the event's authenticity and confirms its origination from CloudFactory. Conversely, any discrepancy denotes a potential security concern, necessitating the immediate rejection of the event.

By adopting this authentication process, CloudFactory safeguards client data integrity and empowers clients to utilize reliable information for optimized decision-making confidently.

VERIFY WEBHOOK HEADER

As the webhook endpoint is open, clients can verify the request is valid using following mechanism:

Step 1: Extract the timestamp and signatures from the header

Firstly, split the X-CF-Signature header value using the ; character as the separator to get a list of elements. Then split each element using the = character as the separator to get a prefix and value pair. The t corresponds to the timestamp, v1 corresponds to the signature.

Step 2: Prepare signed_payload

Concatenate the following to create a signed_payload string:

• the timestamp t

• the character .

• the request body

Step 3: Generate the expected signature

Generate a unique security code (HMAC) using SHA256, where the secret key is the API Key and the signed_payload string as the message.

Step 4: Compare against the signature

Check if the newly generated security code is the same as the signature (v1) provided, if it matches we can make sure the API webhook is valid.

Example:

# import hashlib
# import hmac

# header_string is header ( X-CF-Signature)
# E.g.  "t=1710343835;v1=ce7551796****2ee1"  
# and api key is key used to create the task `X-Api-Token`

def validate_signature(header_string, api_key, response):
  parts = header_string.split(';')
    parsed_data = {}


    for part in parts:
        key, value = part.split('=')
        parsed_data[key] = value


    timestamp = parsed_data.get('t')
    hashed_sign = parsed_data.get('v1')


    if timestamp is None or hashed_sign is None:
        return False


    combined = f"{timestamp}.{response}"
    hmac_obj = hmac.new(api_key.encode('utf-8'), combined.encode('utf-8'), hashlib.sha256)
    calculated_hash = hmac_obj.hexdigest()


    return hashed_sign == calculated_hash

ADDITIONAL TIPS

• Use HTTPS Endpoint: To guarantee secure webhook delivery, exclusively configure callback_url with https:// URLs for TLS encryption and verify they point to applications solely under your ownership.

• Prevent Replay Attacks:

  • Check if the timestamp is not too old.

  • Check if the webhook for the task request id has already been acknowledged by the system.

WEBHOOK WORKFLOW

WEBHOOK EVENT CONTRACT

Event	Description	Sample Payload
task.error	There has been an error processing the task	{    "uuid": "1b6b786f-403a-459f-8b33-b0b69a437d4b",    "event_type":"task.error",    "timestamp":"2024-01-29T16:05:00Z",    "request_id":"b071b22e-288c-42e6-9a35-cbc4ad924143",    "diagnostic": {      "workstream_id":"7454a96f-0e30-4569-8ae4-182344728963",      "configuration_id":"8eb6edff-bad2-4e16-aba3-759359792f99",      "tool_project_id": "a66d2dd4-e742-48e3-b3fc-74ac372c7660"    } }
task.result_available	Results are now available	{    "uuid" :"438d3604-bde6-466e-a143-76aec462ebad",    "event_type": "task.resultavailable",    "timestamp": "2024-01-29T16:05:00Z",    "request_id": "b071b22e-288c-42e6-9a35-cbc4ad924143",    "diagnostic": {      "workstream_id":"7454a96f-0e30-4569-8ae4-182344728963",      "configuration_id": "8eb6edff-bad2-4e16-aba3-759359792f99",      "tool_project_id": "a66d2dd4-e742-48e3-b3fc-74ac372c7660"    } }
task.result_avalilable	Results are now available with extra metadata. Note: Configuration change required from CloudFactory personnel	{    "uuid" :"438d3604-bde6-466e-a143-76aec462ebad",    "event_type": "task.resultavailable",    "timestamp": "2024-01-29T16:05:00Z",    "request_id": "b071b22e-288c-42e6-9a35-cbc4ad924143",    "diagnostic": {      "workstream_id":"7454a96f-0e30-4569-8ae4-182344728963",      "configuration_id": "8eb6edff-bad2-4e16-aba3-759359792f99",      "tool_project_id": "a66d2dd4-e742-48e3-b3fc-74ac372c7660"    },    "task_details": {      "state": "COMPLETED",      "updated_tags":[      {        "confidence_score": 0,        "value": "Left"       }      ],      "existing_tags":[      {        "confidence_score": 0,        "value": "Left"       }      ]   },   "metadata":[    {      "key": "image-0",      "value": "url"      }    ] }

Event Object

Field	Type	Description
uuid	string	A unique identifier for the event.
event_type	string	The type of event that occurred. In this case, "task.error"
timestamp	string	The time the event occurred in UTC.
task_id	string	The task identifier.
diagnostic	array	An array of key-value pairs containing diagnostic information about the event.
diagnostic.workstream_id	string	The identifier for the workstream that the event occurred in.
diagnostic.configuration_id	string	The identifier for the configuration that the event occurred in.
diagnostic.tool_project_id	string	The identifier for the tool project that was used when the event occurred.
task_details	object	An object containing internal state of the tasks.
task_details.state	string	The task state at the time of the webhook.
task_details.exisiting_tags	array	The tags associated with the task provided by the clients.
task_details.updated_tags	array	The tags associated with the task updated by CloudFactory.
metadata	array	An array of key-value pairs containing client specific data.