Webhook configuration

Webhooks allow the Point11 platform to push real-time event notifications to your application via HTTP POST requests. Instead of polling the API for status changes, your application receives events as they happen. This is the recommended integration pattern for audit completion notifications, tracking anomaly alerts, and scheduled report delivery.

How Webhooks Work

When an event occurs in Point11 (an audit completes, a tracking anomaly is detected, a scheduled report is generated), the platform sends an HTTP POST request to the URL you have configured. Your endpoint must respond with a 2xx status code within 30 seconds to acknowledge receipt. If the request fails or times out, Point11 retries with exponential backoff for up to 72 hours.

Creating a Webhook

POST /v1/webhooks
Authorization: Bearer {access_token}

{ "url": "https://your-app.example.com/webhooks/point11", "events": ["audit.completed", "alert.triggered", "report.ready"], "secret": "whsec_your_signing_secret_here" } `

Response

json{
  "id": "whk_9mN4pQr2xK",
  "url": "https://your-app.example.com/webhooks/point11",
  "events": ["audit.completed", "alert.triggered", "report.ready"],
  "status": "active",
  "created_at": "2026-02-13T10:30:00Z"
}

Supported Events

• audit.completed: Fired when an audit finishes processing. Includes the audit ID, type, summary scores, and critical finding count.
• audit.failed: Fired when an audit encounters an unrecoverable error. Includes the error reason and the audit ID.
• alert.triggered: Fired when a monitoring alert condition is met, such as conversion tracking dropping below a threshold, server-side container errors, or consent rate anomalies.
• alert.resolved: Fired when a previously triggered alert condition returns to normal.
• report.ready: Fired when a scheduled report has been generated and is available for download.
• tracking.anomaly: Fired when the platform detects an anomaly in conversion tracking data, such as a sudden drop in tag firing rate or an unexpected change in enhanced conversion match rates.

Webhook Payload Structure

All webhook payloads follow a consistent structure:

json{
  "id": "evt_a1b2c3d4e5",
  "type": "audit.completed",
  "created_at": "2026-02-13T10:34:22Z",
  "data": {
    "audit_id": "aud_8xk2mN4pQr",
    "type": "google_ads_account",
    "summary": {
      "total_findings": 14,
      "critical": 2,
      "warning": 7,
      "info": 5,
      "overall_score": 72
    }
  }
}

Verifying Webhook Signatures

Every webhook request includes a signature header that you must verify to ensure the request originated from Point11 and has not been tampered with:

X-Point11-Signature: sha256=a1b2c3d4e5f6...
X-Point11-Timestamp: 1707820462

To verify the signature:

1. Concatenate the timestamp and the raw request body, separated by a period: {timestamp}.{body}.
2. Compute an HMAC-SHA256 hash of the concatenated string using your webhook secret as the key.
3. Compare the computed hash to the signature value in the header using a constant-time comparison function.
4. Reject requests where the timestamp is more than 5 minutes old to prevent replay attacks.

Never skip signature verification. An unverified webhook endpoint is vulnerable to spoofed events that could trigger unintended actions in your application.

Managing Webhooks

List Webhooks

GET /v1/webhooks
Authorization: Bearer {access_token}

Update a Webhook

PATCH /v1/webhooks/{webhook_id}
Authorization: Bearer {access_token}

{ "events": ["audit.completed", "alert.triggered"], "status": "active" } `

Delete a Webhook

DELETE /v1/webhooks/{webhook_id}
Authorization: Bearer {access_token}

Test a Webhook

Send a test event to verify your endpoint is configured correctly:

POST /v1/webhooks/{webhook_id}/test
Authorization: Bearer {access_token}

This sends a synthetic event of type webhook.test to your configured URL.

Retry Policy

Failed deliveries are retried with exponential backoff: 1 minute, 5 minutes, 30 minutes, 2 hours, 12 hours, 24 hours, and 48 hours. After all retries are exhausted, the webhook is marked as failing and an email notification is sent to the account owner. You can view delivery logs and retry history in the Point11 dashboard under Settings > Webhooks > Delivery Log.

Best Practices

• Respond to webhooks with a 200 status code immediately, then process the event asynchronously. Long-running processing should happen in a background job.
• Implement idempotency using the event ID. The same event may be delivered more than once during retries.
• Use a message queue (SQS, RabbitMQ, Pub/Sub) between your webhook endpoint and your event processing logic to handle traffic spikes.

Sources

• OWASP Webhook Security: https://cheatsheetseries.owasp.org/cheatsheets/Webhook_Security_Cheat_Sheet.html
• HMAC-SHA256 Specification (RFC 2104): https://datatracker.ietf.org/doc/html/rfc2104
• Webhook Best Practices — Stripe Documentation: https://docs.stripe.com/webhooks/best-practices
• Standard Webhooks Specification: https://www.standardwebhooks.com/