Skip to content
Spacefast Docs
Esc
↑↓navigate↵open⌘Jpreview

Create a webhook

Creates a webhook delivering the selected activity events to a public HTTPS endpoint. The signing secret is returned only in this response.

POST/v1/webhooks
Authorization
AuthorizationBearer token · headerrequired
Better Auth session, OAuth access token, OAuth client-credentials token, or sfm_ Space machine credential.
or
AuthorizationOAuth2 access token · headerrequired
OAuth 2.0 with explicit Spacefast capability scopes. Use the authorization-code flow for people and client credentials for machines.
Scopes:spaces:write
Request body
requiredapplication/json
teamIdstring
min length 1
urlstring<uri>required
eventsstring[]
min items 1 · default: ["*"]
Responses
201Response for status 201
$schemastring<uri>
Canonical JSON Schema URL for this response body. The server also sends it in the `Link: rel="describedby"` response header.
dataobjectrequired
Show properties
idstringrequired
urlstring<uri>required
eventsstring[]required
statusstringrequired
Allowed:activedisabledfailingdeleted
secretstring
secretPreviewstringrequired
previousSecretExpiresAtstring<date-time> | anyrequired
Show properties
Any of:
string<date-time>
string<date-time>
any
any
createdAtstring<date-time>required
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))$
updatedAtstring<date-time>required
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))$
defaultProblem details (RFC 9457). Any 4xx/5xx response is one `application/problem+json` document.
$schemastring<uri>
Canonical JSON Schema URL for this response body. The server also sends it in the `Link: rel="describedby"` response header.
typestringrequired
Problem type URI resolving to the error docs page. The server derives it mechanically from `code` against the docs origin.
titlestringrequired
Short human-readable summary of the problem type. The server derives it mechanically from `code`.
statusintegerrequired
HTTP status code of this response, repeated in the body.
min -9007199254740991 · max 9007199254740991
detailstringrequired
Human-readable failure explanation for this occurrence.
codestringrequired
Stable snake_case error code naming the failed public contract.
pointerstring
RFC 6901 JSON Pointer into the failing request field, for example "/files/37/path", on validation failures.
detailsobject
Machine-readable context for the error code.
suggestionsstring[]
Actionable recovery steps safe to show in dashboards, SDKs, and CLI output.
nextstring[]
Copy-pasteable commands or API requests an agent can run next.
requestIdstringrequired
The request id to quote when contacting support.
Request
curl -X POST "https://api.spacefast.com/v1/webhooks" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "teamId": "string",
  "url": "http://example.com",
  "events": [
    "*"
  ]
}'
Response
{
  "$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"
  }
}