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.

X-CF-Signature: t=<timestamp>;v1=<signature>

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):
  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_token.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 Object