Documentation menu

← Webhooks

API reference

Create a webhook

POST/v1/webhook

Creates a webhook that sends the events you choose to your URL.

The response includes the signing secret, secret, which is shown only once. Use it to verify the webhook-signature header on each delivery. The URL must use https, be reachable from the internet and contain no credentials.

Parameters

No parameters.

Request body

urlrequiredstring
The URL deliveries are sent to. Must be https and reachable from the internet. Redirects are not followed.
namestring | null
A name for the webhook, up to 200 characters.
event_typerequired"permit.created" | "case.created"[]
The event types delivered to this webhook.
activeboolean
Whether events are delivered. While false, deliveries are held. Defaults to true.
retry_policyRetryPolicy | null
The retry policy. Omitted fields take their defaults.
Show fields
max_attemptinteger
Maximum attempts per delivery, between 1 and 20. Defaults to 12.
backoff"exponential" | "linear" | "fixed"
How the wait between attempts grows. One of exponential (doubles), linear (adds base_seconds) or fixed. No wait exceeds six hours. Defaults to exponential.
base_secondsinteger
Seconds to wait after the first failed attempt, between 1 and 3600. Defaults to 60.
jitterboolean
Whether each wait is randomized to between half and all of its length. Defaults to true.
dead_letter_after_hoursinteger
Hours after the event after which retries stop, between 1 and 720. Defaults to 24.

Responses

201
CreatedWebhook
The webhook.
401
ProblemDetail
credential_missing, credential_invalid or credential_expired. The request has no valid credential.
403
ProblemDetail
scope_missing, person_required, api_key_not_accepted or entitlement_missing. The credential or plan does not allow this request. detail names the reason.
422
ProblemDetail
parameter_invalid, id_malformed or a cursor code. A parameter is missing or invalid. errors lists each one.
429
ProblemDetail
rate_limited. Too many requests. Retry after the Retry-After interval. Nothing is charged.

Credits

Free.

Example request

curl -X POST 'https://api.placestack.com/v1/webhook' \
  -H "Authorization: Bearer $PLACESTACK_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://example.com/webhook",
  "event_type": [
    "permit.created"
  ]
}'

Example response

{
  "object": "webhook",
  "id": "whk_01h455vb4pex5vsknk084sn02q",
  "name": "Production",
  "url": "https://example.com/webhooks/placestack",
  "event_type": [
    "permit.created"
  ],
  "active": true,
  "secret_fingerprint": "9f86d081",
  "retry_policy": {
    "max_attempt": 12,
    "backoff": "exponential",
    "base_seconds": 60,
    "jitter": true,
    "dead_letter_after_hours": 24
  },
  "created_at": "2026-09-13T12:00:00Z",
  "updated_at": "2026-09-13T12:00:00Z",
  "href": "/webhook/whk_01h455vb4pex5vsknk084sn02q",
  "secret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw"
}

Next steps

GET /webhook/{webhook}

Retrieve a webhook

Continue