Documentation menu

← Webhooks

API reference

Update a webhook

PATCH/v1/webhook/{webhook}

Updates a webhook's URL, name, event types, active status or retry policy.

event_type and retry_policy replace their current values. Send the ETag you read as If-Match. The signing secret does not change.

Parameters

path

webhookrequiredstring
The webhook's id, whk_....

header

If-Matchstring | null
The ETag from your last read of the webhook. A stale value is refused with 409.

Request body

urlstring | null
The URL deliveries are sent to. Pending deliveries go to the new URL.
namestring | null
A name for the webhook, up to 200 characters. null clears it.
event_type"permit.created" | "case.created"[] | null
The complete list of event types to deliver. Replaces the current list.
activeboolean | null
Whether events are delivered. While false, deliveries are held.
retry_policyRetryPolicy | null
The retry policy. Replaces the current policy, and omitted fields take their defaults. null restores every default.
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

200
webhook object
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.
404
ProblemDetail
no_such_resource. No object has that id.
409
ProblemDetail
version_conflict. The object changed after it was read. Read it again and resend with the new ETag in If-Match.
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 PATCH 'https://api.placestack.com/v1/webhook/018f4b75-6f79-7c6a-8c80-000000000001' \
  -H "Authorization: Bearer $PLACESTACK_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://example.com"
}'

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"
}

Next steps

DELETE /webhook/{webhook}

Delete a webhook

Continue