Integrations

Webhook Integration

Set up custom webhooks to receive APVISO events at any HTTPS endpoint with signed payloads and automatic retries.

What Are Webhooks?

Webhooks let you receive APVISO events at any HTTPS endpoint you control. When a subscribed event occurs, APVISO sends an HTTP POST request with a JSON payload containing the event data. This is the most flexible integration option — you can build any custom workflow.

Setting Up a Webhook

  1. Go to Settings → Integrations → Add Integration → Webhook.
  2. Enter your Endpoint URL. It must use HTTPS — HTTP endpoints are rejected for security.
  3. Select the events you want to receive.
  4. Optionally set a secret for payload signing (strongly recommended).
  5. Click Save.

Payload Format

Webhook payloads are JSON objects with a consistent structure:

json
{
  "event": "finding.created",
  "timestamp": "2026-04-10T14:30:00Z",
  "data": {
    "id": "01961234-5678-7abc-def0-123456789abc",
    "scanId": "01961234-0000-7abc-def0-123456789abc",
    "title": "SQL Injection in /api/users",
    "severity": "critical",
    "cwe": "CWE-89",
    "url": "https://app.apviso.com/findings/01961234-5678-7abc-def0-123456789abc"
  }
}

The data object varies by event type but always includes an id and a link back to the APVISO dashboard.

Payload Signing

When you configure a webhook secret, APVISO signs every payload using HMAC-SHA256. The signature is included in the X-APVISO-Signature header. To verify:

python
import hmac
import hashlib

def verify_signature(payload_body, secret, signature_header):
    expected = hmac.new(
        secret.encode(),
        payload_body,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature_header)

Always verify signatures to ensure payloads are genuinely from APVISO.

Retry Behavior

APVISO expects your endpoint to respond with a 2xx status code within 10 seconds. If delivery fails:

  • Retry 1 — after 1 minute.
  • Retry 2 — after 5 minutes.
  • Retry 3 — after 30 minutes.

After 3 failed retries, the delivery is marked as failed. Consecutive failures (10+) will automatically disable the webhook, and you will receive an email notification.

Delivery Logs

View recent deliveries, their status codes, and response times in the webhook's detail page. You can manually retry failed deliveries from the log.

Best Practices

  • Always use HTTPS with a valid TLS certificate.
  • Always configure and verify a webhook secret.
  • Respond to webhooks quickly (within 5 seconds) and process events asynchronously.
  • Implement idempotency — APVISO may deliver the same event more than once during retries.
  • Monitor the delivery log regularly for failures.
Back to Knowledge Base