Update a webhook

Updates the endpoint, the subscribed filters, or the status, and returns the updated webhook. Fields left out keep their value, and events replaces the whole filter list. Secrets change only through the rotate operation. A webhook declared in a tenant manifest is configured there and rejected here.

PATCH/v1/webhooks/{webhookId}

Authorization

AuthorizationBearer token · headerrequired

`Authorization: Bearer ` with an API key (`sfa_` prefix), an OAuth access token, a session token, or a Space machine credential (`sfm_` prefix).

or

AuthorizationOAuth2 access token · headerrequired

OAuth 2.0 with Spacefast scopes. People use the authorization code flow; machines use client credentials.

Scopes:spaces:write

Path parameters

webhookIdstringrequired

min length 1

Request body

requiredapplication/json

urlstring

Public HTTPS endpoint that receives each event. Loopback and private-network hosts are rejected.

eventsstring[]

Replaces the subscribed filters. Every filter must name a known event code.

min items 1

statusstring

Set disabled to stop deliveries without deleting the webhook.

Allowed:active``disabled

Responses

200Response for status 200

$schemastring

Canonical JSON Schema URL for this response body. The server also sends it in the `Link: rel="describedby"` response header.

dataobjectrequired

Show propertiesHide properties

idstringrequired

urlstringrequired

eventsstring[]required

Event filters this webhook is subscribed to.

statusstringrequired

`active` delivers. `failing` follows 8 consecutive failures and still delivers. `disabled` follows 32 and stops. `deleted` is kept for audit only. Any success resets the count.

Allowed:active``disabled``failing``deleted

secretstring

Signing secret, present only in the response that created the webhook or rotated its secret. Store it then; it cannot be read back.

secretPreviewstringrequired

First eight and last four characters of the current signing secret.

previousSecretExpiresAtstring | anyrequired

ISO 8601 timestamp when the secret replaced by the last rotation stops being accepted. Null when no earlier secret is still valid.

Show propertiesHide properties

Any of:

string

string<date-time>

any

any

createdAtstringrequired

matches ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$

updatedAtstringrequired

$schemastring

Canonical JSON Schema URL for this response body. The server also sends it in the `Link: rel="describedby"` response header.

Error Response

typestringrequired

URL of the documentation page for this error. Derived from `code`.

titlestringrequired

Human-readable name of the error type. Derived from `code`.

statusintegerrequired

HTTP status of the response, repeated in the body.

min -9007199254740991 · max 9007199254740991

detailstringrequired

What went wrong in this request.

codestringrequired

Stable snake_case error code. Match on this, not on `detail`.

pointerstring

RFC 6901 JSON Pointer to the request field or batch entry that failed, for example `/files/37/path`. Present on validation failures.

detailsobject

Machine-readable context keyed by the error code.

suggestionsstring[]

Recovery steps safe to show to a person.

nextstring[]

Commands or API requests to run next, usable as written.

requestIdstringrequired

ID of this request, from the `X-Request-Id` header or generated. Quote it when contacting support.

Example

cURL

curl -X PATCH "https://api.spacefast.com/v1/webhooks/string" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "http://example.com",
  "events": [
    "string"
  ],
  "status": "active"
}'

JavaScript

const response = await fetch("https://api.spacefast.com/v1/webhooks/string", {
  method: "PATCH",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  },
  body: "{\n  \"url\": \"http://example.com\",\n  \"events\": [\n    \"string\"\n  ],\n  \"status\": \"active\"\n}"
});

Python

import requests

response = requests.patch(
    "https://api.spacefast.com/v1/webhooks/string",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Content-Type": "application/json"
    },
    data="{\n  \"url\": \"http://example.com\",\n  \"events\": [\n    \"string\"\n  ],\n  \"status\": \"active\"\n}",
)

JSON Responses

200 default

{
  "$schema": "http://example.com",
  "data": {
    "id": "string",
    "url": "http://example.com",
    "events": [
      "string"
    ],
    "status": "active",
    "secret": "string",
    "secretPreview": "string",
    "previousSecretExpiresAt": "2019-08-24T14:15:22Z",
    "createdAt": "2019-08-24T14:15:22Z",
    "updatedAt": "2019-08-24T14:15:22Z"
  }
}

Error

{
  "$schema": "http://example.com",
  "type": "string",
  "title": "string",
  "status": -9007199254740991,
  "detail": "string",
  "code": "string",
  "pointer": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "suggestions": [
    "string"
  ],
  "next": [
    "string"
  ],
  "requestId": "string"
}