spotlight_hook

The spotlight_hook resource, and the API's hook kind: a team's rule that runs steps when an event happens to one of the team's tasks.

See Resource API for the operations, headers and errors every kind shares.

ExampleCopy Anchor Link

resource "spotlight_hook" "migrations" {
  team_id = spotlight_team.core.id
  key     = "migrations-need-a-dba"
  on      = "pull-request.opening"
  match = {
    paths = ["db/migrations/**"]
  }
  steps = [
    {
      name    = "review"
      request = { url = "https://dba.acme.dev/review" }
    },
  ]
  signing = {
    oidc = { audience = "https://dba.acme.dev" }
  }
  failure         = "block"
  timeout_seconds = 20
}

FieldsCopy Anchor Link

In Terraform, signing.secret is the write-only signing.secret_wo, and signing.secretVersion is signing.secret_wo_version.

A hook fires when every non-empty match list matches and when holds. An empty list matches everything.

Glob syntax in match.paths:

EventsCopy Anchor Link

A before event waits while its hooks run, and a hook can stop it. An after event has already happened; its hooks are queued and run afterwards.

changed is a list of paths. Expressions on an event in a run also see run.id. See Hook values for every value an expression sees.

StepsCopy Anchor Link

A step names exactly one of call and request. Steps run in order. A step that fails stops the steps after it.

A step may not call a tool with approval, or a tool of an integration whose connection.holder is requester; the step fails with not-allowed. For the second, the reason is names <tool>, which acts as the person who started a task. A hook acts as nobody.

request:

Every request is a POST. Without body, the body is:

{ "hook": "<key>", "on": "<event>", "occurrence": "<id>", "event": {}, "task": {}, "run": { "id": "<run id>" } }

run is null on an event outside a run. A step's output is its response body, parsed as JSON when it is JSON, cut at 16 KiB.

Request headersCopy Anchor Link

On a self-hosted Spotlight, use your deployment's address in place of app.usespotlight.ai.

SigningCopy Anchor Link

signing is either { secret, secretVersion } or { oidc }.

HMACCopy Anchor Link

The signature follows Standard Webhooks:

webhook-signature: v1,<base64 of HMAC-SHA256(key, "<webhook-id>.<webhook-timestamp>.<body>")>

The key is the bytes the part after whsec_ decodes to.

OIDCCopy Anchor Link

The request carries Authorization: Bearer <token>, an ES256 JWT:

A hook with oidc is refused when the deployment has no key to sign hook tokens with, in HOOK_SIGNING_KEY: needs HOOK_SIGNING_KEY set to sign OIDC tokens.

Refusing an eventCopy Anchor Link

A hook on a before event refuses the event when:

• a step's response is 2xx with a JSON body whose refuse is a non-empty string, whatever failure is; or
• a step fails and failure is block.

{ "refuse": "Migrations need a DBA's review first." }

The event is refused with Hook <key> refused. Reason: <reason>, or Hook <key> failed at step <step> and blocks on failure. Reason: <reason>. With continue, a failed step lets the event go on.

The hooks on one before event have 60 seconds together.

CallbacksCopy Anchor Link

The token in spotlight-callback-token lives 15 minutes and is sent as Authorization: Bearer <token>.

POST /api/hook-callbacks/notes takes an optional Idempotency-Key; a retry with the same key is said once. A missing, expired or unknown token is refused with 401. An empty or too long note is refused with 400.

FailuresCopy Anchor Link

A hook on an after event is retried up to 8 attempts in all, from 2 seconds apart doubling to 1 hour. A hook on a before event is not retried.

Loop guardCopy Anchor Link

Every firing of a hook on an after event carries the chain of firings and events that caused it. A webhook delivery to Spotlight that carries the spotlight-cause header it was sent, or a callback, joins that chain. A firing is stopped with loop when:

A stopped firing is reported on the task.