DocsBook a demo

Platform

Platform overviewArchitectureWorkflow orchestrationGitOps configurationGovernance and AAAAI and MCPKnowledge and contextRuntime and executionEvidence and monitoring

Use cases

All use casesProduction incidentRelease preparationHotfix to productionSecurity scan triage
Why NopsAIIntegrationsSecurity

Resources

All resourcesAI agent governanceMCP governanceMCP securitySelf-hosted platforms
PricingGitHub

Company

How a run worksAboutContactBook a demo

External API triggers

Let another system start a run, with explicit callers, payload validation, mapping, and rate limits.

ReferenceAutomation authorDeveloperSecurity

Key points

  • allowed_callers names explicit user, service_account, or auth_team callers.
  • variable_mapping pulls run variables from event_type, payload.<path>, variables.<name>, a direct payload path, or literal:<value>.
  • payload_schema guards required fields and basic property types before a run starts.
  • rate_limit.per_minute caps invocations over the previous minute.
  • idempotency_key on the request is scoped by trigger and caller, so a retry returns the original run.

Field reference

nameexternal triggerstringRequiredNone

Trigger name used in the API path and the UI registry.

Example

name: deploy-from-servicenow

Evidence

services/nopsai/external_triggers_gitops.go

pipelineexternal triggerstringRequiredNone

Pipeline started when the trigger is invoked.

Example

pipeline: platform/deploy-service

Evidence

services/nopsai/external_triggers_gitops.go

enabledexternal triggerbooleanOptionaltrue

Whether invocations are accepted. Disabled triggers reject calls without starting a run.

Example

enabled: true

scopeexternal triggerstringOptionalDefault runtime scope

Runtime scope used to resolve variables and secrets for triggered runs.

Example

scope: platform/production

run_team_pathexternal triggerstringOptionalglobal

Team path applied to the resulting Pipeline Run for ownership and notifications.

Example

run_team_path: platform/payments

allowed_callersexternal triggerobject[]OptionalNone

Explicit callers permitted to invoke the trigger.

Example

allowed_callers:
  - service_account: release-bot
  - auth_team: platform/sre

Allowed values

user, service_account, auth_team

Security

An empty list does not widen access; AAA still authorizes the caller against the trigger resource.

Evidence

services/nopsai/external_triggers_gitops.go

variable_mappingexternal triggermap<string,string>OptionalNone

Maps invocation data into run variables. Sources are event_type, payload.<path>, variables.<name>, a direct payload path, or literal:<value>.

Example

variable_mapping:
  SERVICE: payload.service.name
  ENVIRONMENT: literal:production

Evidence

services/nopsai/external_triggers_gitops.go

payload_schemaexternal triggerobjectOptionalNone

Object-schema guard with required fields and basic property type checks applied before a run starts.

Example

payload_schema:
  type: object
  required: [service]
  properties:
    service:
      type: string

Evidence

services/nopsai/external_triggers_gitops.go

rate_limit.per_minuteexternal triggerintegerOptionalNone

Maximum invocations accepted for this trigger over the previous minute.

Example

rate_limit:
  per_minute: 30

Evidence

services/nopsai/external_triggers_gitops.go

idempotency_keyinvoke requeststringOptionalNone

Retry key sent on the invoke request. Scoped by trigger and caller so a repeated call returns the original run instead of starting a second one.

Example

{"idempotency_key": "change-4821"}

Evidence

services/nopsai/external_triggers.go

Examples

Change-management triggeryaml
name: deploy-from-change-request
pipeline: platform/deploy-service
enabled: true
scope: platform/production
run_team_path: platform/payments
allowed_callers:
  - service_account: change-management
payload_schema:
  type: object
  required: [service, change_id]
  properties:
    service: { type: string }
    change_id: { type: string }
variable_mapping:
  SERVICE: payload.service
  CHANGE_ID: payload.change_id
  ENVIRONMENT: literal:production
rate_limit:
  per_minute: 10
Invoking with an idempotency keybash
curl -sX POST "$NOPSAI_URL/v1/external-triggers/$TRIGGER_ID/invoke" \
  -H "Authorization: Bearer $NOPSAI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"idempotency_key":"change-4821","payload":{"service":"payments","change_id":"4821"}}'
Result

A repeated call with the same key returns the original run instead of starting a second one.

How it works

An empty allowed_callers list does not widen access. AAA still authorizes the caller against the trigger resource, so the list narrows an already-authorized set rather than granting anything.

Invocation history is available per trigger, which is usually the fastest way to diagnose a caller that believes it is triggering runs but is being rejected.

Implementation evidence

  • services/nopsai/external_triggers_gitops.go

    External trigger GitOps document schema.

  • services/nopsai/external_triggers.go

    Invocation, idempotency, and rate-limit handling.