Webhooks

Receive signed events when Northstar resources change.

Webhooks notify your application when deployments and projects change. Each delivery is an HTTPS POST request containing a JSON event.

Create an endpoint

Configure a public HTTPS URL and select the events your application needs:

json

{
  "url": "https://app.example.com/webhooks/northstar",
  "events": ["deployment.succeeded", "deployment.failed"]
}

Event payload

json

{
  "id": "evt_01J8Z9E4KS",
  "type": "deployment.succeeded",
  "created_at": "2026-08-04T06:15:00Z",
  "data": {
    "deployment_id": "dep_01J8Z41DQP",
    "project_id": "prj_01J8YQ2N7F"
  }
}

Verify signatures

Northstar signs the raw request body with your endpoint secret. Compute an HMAC SHA-256 signature and compare it with the northstar-signature header using a timing-safe comparison.

Reject requests with an invalid signature or a timestamp older than five minutes.

Delivery behavior

Return a 2xx response as soon as the event is accepted. Process long-running work asynchronously. Failed deliveries are retried with exponential backoff for up to 24 hours.

Webhook handlers must be idempotent because the same event can be delivered more than once.

Endpoint examples

Error handling