Create a webhook · API reference

A webhook, subscribed to the events you name and delivering them to your URL.

The URL must be https and reachable from the internet, and must not carry credentials. Duplicate event types are collapsed. The signing secret appears only in this response: store it, and verify every delivery's webhook-signature with it.

Parameters

No parameters.

Request body

urlrequiredstring

An https URL reachable from the internet. Redirects aren't followed.

namestring | null

What this endpoint is for.

event_typerequiredstring[]

The events delivered here.

activeboolean

False holds deliveries until it's true again.

retry_policyRetryPolicy | null

Defaults apply to anything left out.

Show its fields

max_attemptinteger: Calls made before giving up.
backoff"exponential" | "linear" | "fixed": How the wait grows: doubling, adding base_seconds, or not at all. No wait exceeds six hours.
base_secondsinteger: The wait after the first failed call.
jitterboolean: Wait a random half to all of each interval.
dead_letter_after_hoursinteger: Stop retrying this long after the event was created.

Responses

201: CreatedWebhook; Successful Response
401: ProblemDetail; credential_missing, credential_invalid or credential_expired: send a live API key as Authorization: Bearer <key>.
402: ProblemDetail; quota_exhausted: the balance can't cover the call. Nothing was charged and nothing was returned.
403: ProblemDetail; scope_missing, person_required or entitlement_missing: this credential or plan can't do this. detail says which.
404: ProblemDetail; no_such_resource: nothing has that id.
409: ProblemDetail; version_conflict: the record changed since you read it. Read it again and resend.
422: ProblemDetail; parameter_invalid, id_malformed or a cursor code: a parameter's value isn't one this operation takes.
429: ProblemDetail; rate_limited: wait for Retry-After, then send it again. Not charged.

Example request

curl -X POST 'https://api.placestack.com/webhook' \
  -H 'Authorization: Bearer $PLACESTACK_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "<Url>",
  "event_type": [
    "ping"
  ],
  "name": "string",
  "active": true,
  "retry_policy": {
    "max_attempt": 12,
    "backoff": "exponential",
    "base_seconds": 60,
    "jitter": true,
    "dead_letter_after_hours": 24
  }
}'

Example response

{
  "object": "webhook",
  "id": "whk_01h455vb4pex5vsknk084sn02q",
  "name": "string",
  "url": "<Url>",
  "event_type": [
    "ping"
  ],
  "active": true,
  "secret_fingerprint": "<Secret Fingerprint>",
  "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": "<Href>",
  "secret": "<Secret>"
}