跳转到内容
Pidgr Docs

Webhooks

此内容尚不支持你的语言。

Webhooks let you pipe campaign data to external systems. Pidgr has two distinct webhook surfaces:

  • Workflow webhooks (CALL_WEBHOOK step) — covered on this page. A step in the campaign’s workflow that POSTs the campaign’s delivery outcomes (who acknowledged, who missed) to your endpoint, typically when the campaign completes.
  • The generic webhook notification channel — a per-user notification fan-out for reminder and escalation steps, with HMAC-signed requests. See the Generic Webhook Channel page; it is configured separately and carries a different payload.

How Workflow Webhooks Work

Section titled “How Workflow Webhooks Work”
  1. Add a CALL_WEBHOOK step to your campaign’s workflow definition
  2. When the step executes, Pidgr POSTs delivery outcome data to the configured URL as JSON
  3. Your endpoint processes the payload and returns a 2xx status

Configuration

Section titled “Configuration”

Webhooks are configured as workflow steps in the campaign’s workflow definition:

{
  "id": "webhook-step",
  "type": "CALL_WEBHOOK",
  "config": {
    "name": "Results to internal dashboard",
    "url": "https://hooks.example.com/pidgr-results",
    "headers": {
      "Authorization": "Bearer your-webhook-secret",
      "X-Custom-Header": "custom-value"
    }
  },
  "transitions": {}
}

Configuration Fields

Section titled “Configuration Fields”
Field Description Constraints
name Human-readable name for logging Max 200 characters
url HTTPS endpoint to POST to Max 2048 characters, HTTPS required
headers Additional HTTP headers Max 20 entries

Payload Format

Section titled “Payload Format”

The webhook POST body (Content-Type: application/json) summarizes the campaign’s delivery outcomes: a summary object with counts per final delivery status, and a users object with user ID lists grouped by final status.

{
  "campaign_id": "campaign-uuid",
  "org_id": "org-uuid",
  "event": "campaign_completed",
  "summary": {
    "total": 16,
    "acknowledged": 12,
    "missed": 3,
    "no_device": 1,
    "failed": 0
  },
  "users": {
    "acknowledged": ["user-uuid-1", "user-uuid-2"],
    "missed": ["user-uuid-3"],
    "no_device": ["user-uuid-4"],
    "failed": []
  }
}
  • Status keys are lowercased delivery statuses; summary.total is the sum of all counts.
  • The users object always includes the acknowledged, missed, no_device, and failed keys — with empty arrays when no deliveries ended in that status.

SSRF Protection

Section titled “SSRF Protection”

Pidgr enforces strict SSRF (Server-Side Request Forgery) protections on webhook URLs:

Blocked Destinations

Section titled “Blocked Destinations”

The following are rejected in production:

  • Private IPs — 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16
  • Loopback — 127.0.0.0/8, ::1
  • Localhost — localhost (case-insensitive)
  • Link-local — 169.254.0.0/16, fe80::/10 (this blocks cloud metadata endpoints)

Requirements

Section titled “Requirements”
  • URLs must use HTTPS in production
  • The URL’s hostname is resolved via DNS and every resolved IP is checked against the blocked ranges
  • Validation runs before any HTTP request is made; a URL that fails validation is never called

Delivery Behavior

Section titled “Delivery Behavior”
  • Timeout — 10 seconds per request
  • Redirects are not followed — a 3xx response is treated as a failure; point the webhook directly at its final URL
  • Non-2xx is a failure — any non-2xx status marks the call failed
  • Response bodies are ignored — only the first 1KB is read, for diagnostics; keep responses small
  • Idempotency — your endpoint should handle duplicate deliveries gracefully (a failed step can be re-executed)

Handling Failures

Section titled “Handling Failures”

A failed webhook call marks the workflow step as failed. It does not undo or alter the campaign’s deliveries — the payload describes outcomes that have already happened.

Security Best Practices

Section titled “Security Best Practices”
  • Use HTTPS — always use TLS-encrypted endpoints
  • Verify the source — include a secret in a custom header (e.g. Authorization) via the step’s headers config and validate it on your end
  • Validate payloads — parse and validate the JSON structure before processing
  • Respond quickly — return 2xx within the 10-second timeout; process asynchronously if needed
  • Handle duplicates — deduplicate on (campaign_id, event)
Section titled “Related”