Docs
API referenceWebhooks

Create a webhook endpoint

Preview· P9
POST/webhook-endpoints

Registers a URL to receive events. The response includes the endpoint's signing secret, shown only this once. Store it with your other secrets and use it to verify every delivery.

  • url must be a public HTTPS address, without a user name or password. Its host must resolve, and only to public addresses: Agoo checks when you save it and again before every delivery. Agoo doesn't follow redirects.
  • List the event types you want in enabled_events, or ["*"] for every type, including types added later, except watchlist.matched, which an endpoint receives only by listing it.
  • An endpoint created with a test key receives test-mode events (livemode: false) only.

Scope: webhooks:manage · Plan: Growth, Pro and Enterprise in live mode; every plan in test mode.

Authorization

AuthorizationBearer <token>

Send Authorization: Bearer <token> on every request. The token is one of:

PrefixWhat it isWhere it may be used
agoo_sk_live_Secret key, live modeYour servers only
agoo_sk_test_Secret key, test modeYour servers only
agoo_pk_live_Publishable key, live modeBrowsers and apps: create pre-registrations and bookings, read public booking types (with their intake questions) and their free slots, read the visit types open for pre-registration with their public forms. Never lists people.
agoo_pk_test_Publishable key, test modeAs above, in test mode

Admins create keys in Console → Developers → API keys and choose each key's scopes. A key is shown once. Never put a secret key in a URL, a browser or a mobile app.

In: header

Scope: webhooks:manage

Header Parameters

Idempotency-Key*string

A UUID you generate for this operation. If you retry with the same key within 24 hours, Agoo returns the original response instead of acting twice. While the first request is still running, a retry returns conflict. Reusing a key with a different request returns idempotency_key_reused. Responses with rate_limited, internal_error or unavailable aren't stored, so retry those with the same key.

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

curl -X POST "https://example.com/webhook-endpoints" \  -H "Idempotency-Key: 3f6b2a1e-8c4d-4f7a-9b2e-5d1c0a7e9f64" \  -H "Content-Type: application/json" \  -d '{    "url": "https://hooks.voltabank.example/agoo",    "description": "Front desk integration",    "enabled_events": [      "visit.checked_in",      "visit.checked_out",      "delivery.received"    ]  }'
{  "id": "whep_01m2jf0cg0ffyrmjbzsk9t0gtc",  "url": "https://hooks.voltabank.example/agoo",  "description": "Front desk integration",  "enabled_events": [    "visit.checked_in",    "visit.checked_out",    "delivery.received"  ],  "status": "enabled",  "disabled_reason": null,  "secret": "whsec_…",  "created_at": "2026-09-15T12:00:00Z",  "updated_at": "2026-09-15T12:00:00Z"}

List webhook endpoints GET

Returns the webhook endpoints for the mode of your key, newest first. Live and test mode have separate endpoints. Secrets are never included; they are shown once, when you create or rotate them. **Scope:** `webhooks:manage` · **Plan:** Growth, Pro and Enterprise in live mode; every plan in test mode.

Get a webhook endpoint GET

Returns one webhook endpoint, without its secret. Check `status` and `disabled_reason` to see whether Agoo has disabled it after repeated failures. **Scope:** `webhooks:manage` · **Plan:** Growth, Pro and Enterprise in live mode; every plan in test mode.