Skip to main content
Use webhooks to respond to alerts, address tickets, or react to deploys. Use schedules to run audits, triage dependencies, or send weekly reports.

Examples

  • Diagnose Datadog alerts in Slack — when a Datadog monitor fires, the agent investigates with the Datadog MCP and posts the root cause back to the alert’s Slack thread.
  • Weekly flaky test fixes — every Monday morning, the agent scans the last week of GitHub Actions runs for flaky tests and opens a PR with an attempted fix for each.
  • Nightly bug hunt — every night, the agent reads the last 24 hours of commits, flags the riskiest changes, and opens a PR with fixes for any bugs it finds.

Scheduled tasks

Use a schedule for recurring work like dependency bumps, periodic test runs, code-quality scans, or weekly maintenance passes. Configure:
  • Environment, branch, and model
  • Schedule and task: describe in plain language what the agent should do and when it should run. Niteshift parses it into a task prompt, recurrence rule (RRULE), timezone, and a human-readable schedule label.

Webhook triggers

Use a webhook for event-driven work like CI failures, monitoring alerts, deploy notifications, or anything else that emits an HTTP webhook. Configure:
  • Name, environment, branch, and model
  • Task prompt template: the instructions the agent gets each time a request hits the URL. Use {{payload.field}} (dot paths into the JSON) or {{payload_json}} / {{payload}} to insert the full request body as pretty-printed JSON.

Authentication

Each trigger has a single shared secret. Incoming requests authenticate with one of:
  • HMAC (preferred): send x-niteshift-signature and x-niteshift-timestamp headers. The signature is sha256=<hex> where the HMAC is computed over <timestamp>.<body> using the trigger secret. Includes timestamp-based replay protection.
  • Bearer token: send Authorization: Bearer <secret>. Use this for sources like Datadog that can set static custom headers but can’t compute a per-request signature.

Rate limiting

Each webhook URL is limited to 10 requests per rolling minute and 100 per 24 hours. The burst rule runs first; a request only counts toward the daily cap if it would have passed the burst check, so a flood of throttled calls does not use up the whole day. 429 responses: JSON with error and retryAfter (seconds), plus the Retry-After and X-RateLimit-* headers. Header values match whichever limit blocked you; X-RateLimit-Reset is a Unix time in seconds for the end of that limit’s current window.

Store automations in your repository

You can store each automation in your environment’s primary repository. Niteshift will automatically update the automations when changes are committed to your repository’s default branch. Each automation should go in <settingsDirectory>/automations/<key>.mdx. The settings directory is .niteshift or an environment subdirectory, such as .niteshift/backend. For example, .niteshift/automations/weekly-review.mdx:
Replace maintenance-bot with your service account handle.

File format reference

The YAML front matter between --- lines holds the fields below. The rest of the file is used verbatim as the task prompt (1–20,000 characters); braces, JSX, and code are literal text, not executed as MDX. Unknown front-matter or trigger fields are rejected. Optional execution fields let you override the task’s model, agent, and sandbox settings; availability depends on your account and the selected model.

Required front-matter fields

Every file must include these fields, including schemaVersion: 1.

Optional front-matter fields

Choose an agent, model, and provider

  • agent is the coding tool that reads the prompt, edits files, and runs commands. For example, claude selects Claude Code; codex selects Codex.
  • model is the AI model the coding tool uses. claude-sonnet-latest follows the latest Sonnet release; a concrete ID such as claude-sonnet-4-6 pins a version.
  • provider is the service or router that handles requests to that model, such as anthropic, openai, or openrouter. It must support the chosen agent and model and be available to the service account named in runAs.
For Claude Code with Sonnet through Anthropic, add these fields to the front matter:
For Codex through OpenAI, use:

Schedule trigger fields

Each schedule entry in triggers has these fields:

Webhook trigger fields

Each webhook entry in triggers has these fields: For example, replace the schedule’s triggers list with this to run from a webhook:
Never put secrets in the file. You can generate secrets for new webhook triggers in the app. Reapplying a file preserves an existing trigger’s secret.

Migrate existing automations

In an existing Niteshift task, you can prompt it to export automations. It does so via the ns automations export CLI tool, which you can also run within the task terminal. Example usage:
  1. Export your selection; add --target-service-account <handle> for automations that run as a person.
  2. Pause the original UI-managed automations. You can prompt a task to help you do this, or manage it in the UI.
  3. Review and commit the exported files, merge the change into the default branch, and verify that the newly created automations work.
  4. Delete the originals once you’ve verified that the new copies work.
Export leaves the original unchanged; the repository copy is separate.

Limitations

Repository-stored automations have some limitations that don’t apply to UI-configured automations:
  • They can’t use Slack triggers.
  • They can’t file their tasks into projects.
Reach out to support@niteshift.dev if addressing these limitations would help your workflow.