Skill: carloscbrls/cc3po-webhook (version 1.0.0)

--- name: webhook description: Implement secure webhook receivers and senders with proper verification and reliability. version: 1.0.0 metadata: openclaw: emoji: "\U0001FA9D" os: - linux - macos - win32 homepage: https://clawhub.ai/carloscbrls/webhook --- ## Receiving: Signature Verification - Always verify HMAC signature—payload can be forged; don't trust without signature - Common pattern: `HMAC-SHA256(secret, raw_body)` compared to header value - Use raw body bytes—parsed JSON may reorder keys, breaking signature - Timing-safe comparison—prevent timing attacks on signature check - Reject missing or invalid signature with 401—log for investigation ## Receiving: Replay Prevention - Check timestamp in payload or header—reject if too old (>5 minutes) - Combine with signature—timestamp without signature can be forged - Store processed event IDs—reject duplicates even within time window - Clock skew tolerance: allow 1-2 minutes past—but not hours ## Receiving: Idempotency (Critical) - Webhooks can arrive multiple times—sender retries on timeout, network issues - Use event ID for deduplication—store processed IDs in database/Redis - Make handlers idempotent—same event twice should have same effect - Idempotency window: keep IDs for 24-72h—balance storage vs protection ## Receiving: Fast Response - Return 200/202 immediately—process asynchronously in queue - Senders timeout (5-30s typical)—slow processing = retry = duplicates - Minimal validation before 200—signature check, then queue - Background job for actual processing—failures don't affect acknowledgment ## Receiving: Error Handling - 2xx = success, sender won't retry - 4xx = permanent failure, sender may stop retrying—use for bad signature, unknown event type - 5xx = temporary failure, sender will retry—use for downstream issues - Log full payload on error—helps debugging; redact sensitive fields ## Sending: Retry Strategy - Exponential backoff: 1min, 5min, 30min, 2h, 8h—then give up or alert - Cap retries (5-10 attempts)—don't retry forever - Record delivery attempts—show status to user - Different retry for 4xx vs 5xx—4xx often means stop retrying ## Sending: Signature Generation - Include timestamp in signature—prevents replay of captured webhooks - Sign raw JSON body—document exact signing algorithm - Header format: `t=timestamp,v1=signature`—allows versioned signatures - Provide verification code examples—reduce integration friction ## Sending: Timeouts - 5-10 second timeout—don't wait forever for slow receivers - Treat timeout as failure—retry later - Don't follow redirects—or limit to 1-2; prevents redirect loops - Validate HTTPS certificate—don't skip verification ## Event Design - Include event type: `{"type": "order.created", ...}`—receivers filter by type - Include timestamp: ISO 8601 with timezone—for ordering and freshness - Include full resource or ID—prefer full data; saves receiver a lookup - Version events: `api_version` field—allows breaking changes ## Delivery Tracking - Log every attempt: URL, status code, response time, response body - Dashboard for retry queue—let users see pending/failed deliveries - Manual retry button—for stuck webhooks after receiver fix - Webhook logs retention: 7-30 days—balance debugging vs storage ## Security Checklist - HTTPS only—never send webhooks to HTTP endpoints - Rotate secrets periodically—support multiple active secrets during rotation - IP allowlisting optional—document your IP ranges if offered - Don't include secrets in payload—webhook URL should be secret enough - Rate limit per endpoint—one slow receiver shouldn't affect others ## Common Mistakes - No signature verification—anyone can POST fake events to your endpoint - Processing before responding—timeout causes retries, duplicate processing - No idempotency handling—double charges, duplicate records - Trusting event data blindly—always verify by fetching from source API for critical actions


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)