Verify a Webhook#

Use this when your service needs signed operation lifecycle events.

Prerequisites#

A public HTTPS endpoint.
Raw request-body access in your server framework.
Storage for the signing secret returned once on create or rotate.

Create an Endpoint#

curl

request

curl -sS https://api.hightop.com/v1/agent/webhooks \
  -H "content-type: application/json" \
  -H "x-agent-id: $HIGHTOP_AGENT_ID" \
  -H "x-api-key: $HIGHTOP_API_KEY" \
  -H "Idempotency-Key: webhook-create-$(uuidgen)" \
  -d '{
    "url": "https://example.com/hightop/webhook",
    "description": "Production lifecycle webhook",
    "event_types": ["payment.executed", "payment.execution_failed", "conversion.executed", "conversion.execution_failed"]
  }'

Store signing_secret immediately. It is shown once.

Verify Signatures#

Each delivery carries a Hightop-Webhook-Signature HMAC-SHA256 over ${timestamp}.${raw_body}, computed from the raw request body (not parsed JSON). Reject timestamps outside your tolerance window, usually 5-15 minutes.

See Webhooks for the canonical TypeScript verifier and the full signing contract.

Test the Endpoint#

curl

request

curl -sS https://api.hightop.com/v1/agent/webhooks/$WEBHOOK_ID/test \
  -H "content-type: application/json" \
  -H "x-agent-id: $HIGHTOP_AGENT_ID" \
  -H "x-api-key: $HIGHTOP_API_KEY" \
  -H "Idempotency-Key: webhook-test-$(uuidgen)" \
  -d '{}'

Likely errors: validation_failed, limit_exceeded, idempotency_key_reuse_mismatch, insufficient_scope.