TriggersService

The inbound direction: an external app has something happen, and you hear about it. Subscribe an address, read what arrived, and replay a delivery your side missed. Delivery is at least once, with retries and a dead state, and every attempt is readable here.

Every call is a POST to https://api.atmon.ai/automaton.v1.TriggersService/<Call> with a JSON body, and authenticates with Authorization: Bearer <your project key>. Field names in JSON are lowerCamelCase, so the field written tool_slug below is toolSlug on the wire. How to call the API has the whole convention.

Calls

Call	Request	Response	Summary
`CreateSubscription`	`CreateSubscriptionRequest`	`CreateSubscriptionResponse`	Registers an endpoint for delivery and returns its signing secret once.
`ListSubscriptions`	`ListSubscriptionsRequest`	`ListSubscriptionsResponse`	Lists the project's subscriptions.
`DeleteSubscription`	`DeleteSubscriptionRequest`	`DeleteSubscriptionResponse`	Deletes one subscription.
`ListEvents`	`ListEventsRequest`	`ListEventsResponse`	Lists the normalized events received for this project, filtered by toolkit, trigger, and time.
`GetEvent`	`GetEventRequest`	`GetEventResponse`	Reads one event with its normalized payload.
`ListDeliveries`	`ListDeliveriesRequest`	`ListDeliveriesResponse`	Lists delivery attempts for an event, a subscription, or both.
`ReplayEvent`	`ReplayEventRequest`	`ReplayEventResponse`	Queues fresh deliveries for an event to the currently matching active subscriptions, leaving the original attempt history in place so the record of what failed stays readable.
`ListIngestEndpoints`	`ListIngestEndpointsRequest`	`ListIngestEndpointsResponse`	Lists every toolkit that declares an inbound webhook, with the path a provider posts to and whether this deployment holds the secret that verifies it.

CreateSubscription

Registers an endpoint for delivery and returns its signing secret once. HTTPS is required outside loopback.

Request CreateSubscriptionRequest, response CreateSubscriptionResponse.

POST /automaton.v1.TriggersService/CreateSubscription HTTP/1.1
Host: api.atmon.ai
Authorization: Bearer amk_your_project_key
Content-Type: application/json

{
  "endpointUrl": "...",
  "toolkitSlug": "...",
  "triggerSlug": "..."
}

The response:

{
  "subscription": {
    "id": "...",
    "endpointUrl": "...",
    "toolkitSlug": "...",
    "triggerSlug": "...",
    "active": true
  },
  "signingSecret": "..."
}

ListSubscriptions

Lists the project's subscriptions. A signing secret is never returned again, so a lost secret means a new subscription.

Request ListSubscriptionsRequest, response ListSubscriptionsResponse.

POST /automaton.v1.TriggersService/ListSubscriptions HTTP/1.1
Host: api.atmon.ai
Authorization: Bearer amk_your_project_key
Content-Type: application/json

{}

The response:

{
  "subscriptions": [{
    "id": "...",
    "endpointUrl": "...",
    "toolkitSlug": "...",
    "triggerSlug": "...",
    "active": true
  }]
}

DeleteSubscription

Deletes one subscription. Events already stored are unaffected.

Request DeleteSubscriptionRequest, response DeleteSubscriptionResponse.

POST /automaton.v1.TriggersService/DeleteSubscription HTTP/1.1
Host: api.atmon.ai
Authorization: Bearer amk_your_project_key
Content-Type: application/json

{
  "id": "..."
}

The response:

{}

ListEvents

Lists the normalized events received for this project, filtered by toolkit, trigger, and time.

Request ListEventsRequest, response ListEventsResponse.

POST /automaton.v1.TriggersService/ListEvents HTTP/1.1
Host: api.atmon.ai
Authorization: Bearer amk_your_project_key
Content-Type: application/json

{
  "toolkitSlug": "...",
  "triggerSlug": "...",
  "since": "2026-01-31T09:15:00Z",
  "until": "2026-01-31T09:15:00Z",
  "pageSize": 0,
  "pageToken": "..."
}

The response:

{
  "events": [{
    "id": "...",
    "toolkitSlug": "...",
    "triggerSlug": "...",
    "entityId": "...",
    "payloadJson": "{}",
    "occurredAt": "2026-01-31T09:15:00Z",
    "receivedAt": "2026-01-31T09:15:00Z"
  }],
  "nextPageToken": "..."
}

GetEvent

Reads one event with its normalized payload.

Request GetEventRequest, response GetEventResponse.

POST /automaton.v1.TriggersService/GetEvent HTTP/1.1
Host: api.atmon.ai
Authorization: Bearer amk_your_project_key
Content-Type: application/json

{
  "id": "..."
}

The response:

{
  "event": {
    "id": "...",
    "toolkitSlug": "...",
    "triggerSlug": "...",
    "entityId": "...",
    "payloadJson": "{}",
    "occurredAt": "2026-01-31T09:15:00Z",
    "receivedAt": "2026-01-31T09:15:00Z"
  }
}

ListDeliveries

Lists delivery attempts for an event, a subscription, or both. Delivery is at-least-once: pending, delivered, or dead_letter after the last retry.

Request ListDeliveriesRequest, response ListDeliveriesResponse.

POST /automaton.v1.TriggersService/ListDeliveries HTTP/1.1
Host: api.atmon.ai
Authorization: Bearer amk_your_project_key
Content-Type: application/json

{
  "eventId": "...",
  "subscriptionId": "..."
}

The response:

{
  "deliveries": [{
    "id": "...",
    "eventId": "...",
    "subscriptionId": "...",
    "state": "...",
    "attempts": 0,
    "lastError": "...",
    "lastAttemptAt": "2026-01-31T09:15:00Z"
  }]
}

ReplayEvent

Queues fresh deliveries for an event to the currently matching active subscriptions, leaving the original attempt history in place so the record of what failed stays readable.

Request ReplayEventRequest, response ReplayEventResponse.

POST /automaton.v1.TriggersService/ReplayEvent HTTP/1.1
Host: api.atmon.ai
Authorization: Bearer amk_your_project_key
Content-Type: application/json

{
  "eventId": "..."
}

The response:

{
  "deliveries": [{
    "id": "...",
    "eventId": "...",
    "subscriptionId": "...",
    "state": "...",
    "attempts": 0,
    "lastError": "...",
    "lastAttemptAt": "2026-01-31T09:15:00Z"
  }]
}

ListIngestEndpoints

Lists every toolkit that declares an inbound webhook, with the path a provider posts to and whether this deployment holds the secret that verifies it. A read of deployment configuration rather than of project rows: the answer is the same for every project on the node, and it is here because the page that asks "what starts this" is the page that has to say when the answer is nothing.

Request ListIngestEndpointsRequest, response ListIngestEndpointsResponse.

POST /automaton.v1.TriggersService/ListIngestEndpoints HTTP/1.1
Host: api.atmon.ai
Authorization: Bearer amk_your_project_key
Content-Type: application/json

{}

The response:

{
  "endpoints": [{
    "toolkitSlug": "...",
    "path": "...",
    "scheme": "...",
    "secretEnv": "...",
    "secretSet": true
  }]
}

Messages

CreateSubscriptionRequest

Field	Type	#	Notes
`endpoint_url`	`string`	1
`toolkit_slug`	`string`	2	empty subscribes to every toolkit
`trigger_slug`	`string`	3	requires toolkit_slug; empty takes every trigger

CreateSubscriptionResponse

Field	Type	#	Notes
`subscription`	`Subscription`	1
`signing_secret`	`string`	2	signing_secret is returned once, at creation. atmon signs every delivery body with it (X-Automaton-Signature: sha256=<hex>); a lost secret is replaced by a new subscription, never recovered.

DeleteSubscriptionRequest

Field	Type	#	Notes
`id`	`string`	1

DeleteSubscriptionResponse

No fields. The call takes its scope from the authenticated project.

Delivery

Delivery is one attempt series: one event to one subscription.

Field	Type	#	Notes
`id`	`string`	1
`event_id`	`string`	2
`subscription_id`	`string`	3
`state`	`string`	4	pending \| delivered \| dead_letter
`attempts`	`int32`	5
`last_error`	`string`	6
`last_attempt_at`	`google.protobuf.Timestamp`	7

Event

Event is one normalized inbound event, stored per receiving project.

Field	Type	#	Notes
`id`	`string`	1
`toolkit_slug`	`string`	2
`trigger_slug`	`string`	3	the toolkit's kind: trigger tool
`entity_id`	`string`	4	empty when the payload does not resolve one
`payload_json`	`string`	5	normalized body per the trigger's output schema
`occurred_at`	`google.protobuf.Timestamp`	6	provider time when present, else received_at
`received_at`	`google.protobuf.Timestamp`	7

GetEventRequest

Field	Type	#	Notes
`id`	`string`	1

GetEventResponse

Field	Type	#	Notes
`event`	`Event`	1

IngestEndpoint

IngestEndpoint is one toolkit's inbound path and whether this deployment can verify a post to it.

The secret itself is never on this message and there is no RPC that returns it. What crosses is whether the environment variable naming it holds a value, because that single bit decides between a post being accepted and a post being refused, and an operator has no other way to read it.

Field	Type	#	Notes
`toolkit_slug`	`string`	1
`path`	`string`	2	The path a provider posts to, which is /webhooks/ plus the toolkit slug.
`scheme`	`string`	3	The verification scheme the toolkit declares, from the catalog's closed vocabulary: hmac_sha256, slack_v0, token_query.
`secret_env`	`string`	4	The name of the process environment variable holding the shared secret. The name is configuration and is safe to render; the value is not returned.
`secret_set`	`bool`	5	False means every post to this path is refused rather than trusted, so the toolkit's triggers fire nothing until the deployment sets the variable.

ListDeliveriesRequest

Field	Type	#	Notes
`event_id`	`string`	1	filter by event, subscription, or both
`subscription_id`	`string`	2

ListDeliveriesResponse

Field	Type	#	Notes
`deliveries`	repeated `Delivery`	1

ListEventsRequest

Field	Type	#	Notes
`toolkit_slug`	`string`	1	empty lists every toolkit
`trigger_slug`	`string`	2	empty lists every trigger
`since`	`google.protobuf.Timestamp`	3	inclusive lower bound on received_at
`until`	`google.protobuf.Timestamp`	4	exclusive upper bound on received_at
`page_size`	`int32`	5
`page_token`	`string`	6

ListEventsResponse

Field	Type	#	Notes
`events`	repeated `Event`	1
`next_page_token`	`string`	2

ListIngestEndpointsRequest

No fields. The call takes its scope from the authenticated project.

ListIngestEndpointsResponse

Field	Type	#	Notes
`endpoints`	repeated `IngestEndpoint`	1

ListSubscriptionsRequest

No fields. The call takes its scope from the authenticated project.

ListSubscriptionsResponse

Field	Type	#	Notes
`subscriptions`	repeated `Subscription`	1

ReplayEventRequest

Field	Type	#	Notes
`event_id`	`string`	1

ReplayEventResponse

Field	Type	#	Notes
`deliveries`	repeated `Delivery`	1	The freshly enqueued deliveries. Replay leaves the original attempt history in place and queues new deliveries to the currently matching active subscriptions.

Subscription

Subscription is one project endpoint that wants events delivered.

Field	Type	#	Notes
`id`	`string`	1
`endpoint_url`	`string`	2	HTTPS required outside loopback
`toolkit_slug`	`string`	3	empty matches all toolkits
`trigger_slug`	`string`	4	empty matches all triggers of the toolkit
`active`	`bool`	5