Create a webhook subscription

Creates a webhook subscription that fires the voicegram.completed event to the supplied URL on every matching completed voicegram for the account.

Terminal receiver requirement

The URL MUST be a terminal receiver. Your endpoint must respond directly with 2xx/4xx/5xx; a 3xx response is treated as a delivery failure (recorded as redirect_blocked). This applies to real-event delivery, retry delivery, and the dashboard's test-event endpoint.

Secret handling

The response includes the plaintext signing secret ONCE. After this response the plaintext is unrecoverable from the API; secret_prefix is the only identifier surfaced afterwards. Save the plaintext in a secure secret store on your end. If you lose it, delete the subscription and create a new one to rotate.

URL validation

• MUST use HTTPS (http:// returns 400 invalid_url).
• MUST be a valid URI under 2048 characters.
• MUST NOT contain user/password credentials (https://user:pass@host).
• The URL must not point to a private or internal host.

Subscription cap

Active subscriptions per account are capped at 25. The 26th subscription returns 409 limit_reached. Deleted subscriptions don't count toward the cap.

channel_id resolution

If channel_id is provided, it must be a domain or campaign on your account. Returns 400 invalid_channel_id if no match exists.

Endpoint

POST /api/v1/webhook-subscriptions

Authentication

Bearer Personal Access Token. See Authentication.

Request body

Content type: application/json (required).

Example: Zapier-source subscription

{
  "url": "https://hooks.zapier.com/hooks/standard/12345/abc",
  "event_type": "voicegram.completed",
  "channel_id": null,
  "source": "zapier",
  "zapier_subscription_id": "zap-12345-abc"
}

Example: Dashboard-source subscription scoped to a domain

{
  "url": "https://example.com/webhooks/voicegram",
  "event_type": "voicegram.completed",
  "channel_id": "11111111-1111-1111-1111-111111111111",
  "source": "dashboard"
}

Example request

curl -X POST https://www.voicegram.io/api/v1/webhook-subscriptions \
  -H "Authorization: Bearer vg_pat_<your-token>" \
  -H "Content-Type: application/json" \
  -d '{
          "url": "https://hooks.zapier.com/hooks/standard/12345/abc",
          "event_type": "voicegram.completed",
          "channel_id": null,
          "source": "zapier",
          "zapier_subscription_id": "zap-12345-abc"
        }'

Responses

{
  "id": "44444444-4444-4444-4444-444444444444",
  "url": "https://hooks.zapier.com/hooks/standard/12345/abc",
  "secret": "vg_whsec_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
  "secret_prefix": "vg_whsec_012",
  "is_active": true,
  "created_at": "2026-05-14T19:23:45.000Z"
}

{
  "error": "validation_error",
  "issues": [
    {
      "path": [
        "url"
      ],
      "message": "Invalid url"
    }
  ]
}

{
  "error": "invalid_url",
  "message": "URL must be HTTPS and not target a private/internal host.",
  "reason": "host_resolves_to_private_ip: 10.0.0.5"
}

{
  "error": "invalid_channel_id",
  "message": "channel_id does not match any domain or campaign on your account."
}

{
  "error": "limit_reached",
  "message": "Active subscription limit of 25 reached. Delete or disable an existing subscription before creating a new one."
}

{
  "error": "conflict",
  "message": "A subscription with this zapier_subscription_id already exists."
}