Webhook HMAC Verification in the Coasty Computer Use API
When you configure a webhook_url for a task run, Coasty sends HTTP requests to your endpoint with status updates. Each payload is signed using an HMAC-SHA256 digest. You must validate the Coasty-Signature header to confirm the request is authentic and not a replay or tampering attempt. This guide shows how to implement HMAC verification for task run events.
How webhook HMAC verification works
Coasty signs the raw HTTP body of each webhook payload using HMAC-SHA256. The signature is included in the Coasty-Signature header with the format t=unix,v1=hex. You compute the HMAC of the same body using your API key as the secret and compare it against the header value. A match proves the payload came from Coasty and was not altered in transit.
Validate Coasty-Signature header with your API key to ensure webhook authenticity.
Webhook payload structure
The webhook payload for a task run event contains a common structure with event details. The relevant fields include the run id, current state, and any error information if the task failed. You do not parse the body to extract state for this verification step. You only sign the raw body, then compare signatures.
import hmac
import hashlib
import os
from datetime import datetime
def verify_webhook_signature(request_body: bytes, signature_header: str, api_key: str) -> bool:
"""
Verify the HMAC signature of a Coasty webhook payload.
Args:
request_body: Raw HTTP body bytes from the request.
signature_header: The Coasty-Signature header value (e.g., "t=1234567890,v1=abc123...").
api_key: Your Coasty API key from COASTY_API_KEY environment variable.
Returns:
True if the signature is valid, False otherwise.
"""
# Extract timestamp and hex digest from the header
parts = signature_header.split(",")
if len(parts) != 2:
return False
timestamp_part, hex_digest_part = parts
if not timestamp_part.startswith("t=") or not hex_digest_part.startswith("v1="):
return False
timestamp = timestamp_part[2:]
hex_digest = hex_digest_part[3:]
# Compute expected HMAC-SHA256
expected_hmac = hmac.new(
api_key.encode("utf-8"),
request_body,
hashlib.sha256
).hexdigest()
# Use constant-time comparison to prevent timing attacks
return hmac.compare_digest(expected_hmac, hex_digest)
# Example usage in a Flask/FastAPI webhook endpoint
from flask import Flask, request
app = Flask(__name__)
current_api_key = os.getenv("COASTY_API_KEY")
@app.route("/webhook/runs", methods=["POST"])
def webhook_runs():
request_body = request.get_data()
signature_header = request.headers.get("Coasty-Signature")
if not signature_header:
return "Missing Coasty-Signature header", 401
if not current_api_key:
return "Server misconfiguration: COASTY_API_KEY missing", 500
if not verify_webhook_signature(request_body, signature_header, current_api_key):
return "Invalid signature", 401
# Signature valid - process the event
print("Webhook verified, processing event...")
# TODO: Add your business logic here, e.g., update a database, notify a queue, etc.
return "OK", 200
if __name__ == "__main__":
app.run(port=8000, debug=True)Common error states and handling
When a webhook fails validation, return a 401 Unauthorized response. Coasty will retry the webhook request according to its retry policy. If your server is unreachable or returns a non-200 response, Coasty may also retry. Always ensure your webhook endpoint handles edge cases such as malformed headers, missing API key, or invalid payloads gracefully.
Return 401 for invalid signatures to trigger Coasty retry logic.
Where this beats brittle automation
Most automation tools rely on brittle selectors and hardcoded APIs that break when UI changes. The Coasty computer use API lets you drive real desktops, browsers, and terminals like a human agent. By securing those agents with webhook HMAC verification, you ensure only authorized systems can react to task run events. This gives you a robust integration where the agent acts on the actual UI while you remain confident in each webhook callback.
Add HMAC verification to your Coasty webhook endpoint to secure your computer use agent integrations. Test your signature logic with sample payloads and ensure your API key is never exposed. Ready to build secure workflows with the Coasty computer use API? Get your API key at https://coasty.ai/developers and start integrating.