Back to Blog
Engineering

Rachel Kim6 min
Ctrl+H

When you spin up a Task Run or stream events from a workflow, the Coasty platform can POST payloads to your server. Without verification, a malicious actor could spoof events or replay old payloads to cause unexpected actions on your machines. The Coasty webhook security model uses HMAC signatures baked into every event header so you can cryptographically confirm the message truly came from Coasty and has not been tampered with.

How webhook signatures work

Every webhook payload from the Coasty platform includes the following header. This is the only way you can trust the event. Header name: Coasty-Signature Header format: t=<unix_timestamp>,v1=<hex_signature> The signature is generated by Coasty using your webhook secret (a key you set in the dashboard). Coasty HMAC-signs the raw body of the POST request using HMAC-SHA256 with that secret. You recompute the signature locally and compare it to the header value. If they match, the request is authentic and untampered.

python
import hmac
import hashlib
import os
from datetime import datetime, timezone

COASTY_API_KEY = os.getenv("COASTY_API_KEY")
COASTY_WEBHOOK_SECRET = os.getenv("COASTY_WEBHOOK_SECRET")

def verify_webhook_signature(request_body: bytes, signature_header: str) -> None:
    """Raise ValueError if signature does not match."""
    if not signature_header.startswith("t="):
        raise ValueError("Invalid signature header format")
    timestamp_str, expected_sig = signature_header.split(",")
    timestamp = int(timestamp_str[2:])
    # Reject stale requests (e.g., replayed from > 5 minutes ago)
    if datetime.now(timezone.utc).timestamp() - timestamp > 300:
        raise ValueError("Signature timestamp too old")

    # Recompute HMAC-SHA256
    computed = hmac.new(
        COASTY_WEBHOOK_SECRET.encode("utf-8"),
        request_body,
        hashlib.sha256
    ).hexdigest()
    if not hmac.compare_digest(computed, expected_sig):
        raise ValueError("HMAC signature mismatch")

# Example in an async web framework (FastAPI):
from fastapi import Request, HTTPException

@router.post("/webhook/runs")
async def handle_run_webhook(request: Request):
    body = await request.body()
    sig = request.headers.get("Coasty-Signature")
    if not sig:
        raise HTTPException(status_code=401, detail="Missing Coasty-Signature")
    try:
        verify_webhook_signature(body, sig)
    except ValueError as e:
        raise HTTPException(status_code=401, detail=str(e))
    # Process event payload safely here
    payload = await request.json()
    run_id = payload.get("run_id")
    state = payload.get("state")
    # Handle run state changes (queued, running, etc.)
    return {"ok": True, "run_id": run_id, "state": state}

Where to use webhook verification

  • POST /v1/runs: Your system receives run status changes (queued, running, awaiting_human, succeeded, failed, cancelled, timed_out).
  • GET /v1/runs/{id}/events: You can also stream events via Server-Sent Events and validate each chunk with the same signature header if Coasty includes it on SSE.
  • POST /v1/workflows/{id}/runs: Workflow execution results also trigger webhooks, and you should verify them before acting on success/failure.

Use the Coasty-Signature header with HMAC-SHA256 and the webhook secret you configure in the dashboard to cryptographically prove the request is genuine and untampered.

Where this beats brittle automation

Traditional web automation often depends on fragile selectors (CSS or XPath), which break when UI changes, or on direct API calls that may not expose all UI operations. The computer use API empowers an agent to see the screen, interpret natural language, and click, type, and navigate like a human. By coupling that with cryptographically verified webhooks, you can trust that event notifications (state changes, human approvals, workflow milestones) are real, not spoofed. This combination lets you build production-grade agents that react accurately to real-time state without guessing or brittle selectors.

Start building secure computer use agents today. Configure a webhook URL in your Coasty dashboard, set a webhook secret, and use the HMAC verification code above to validate incoming payloads. Head to https://coasty.ai/developers to get your API key and start automating with confidence.

© 2026 Coasty

Backed byYCombinator