Skip to content
Nexa Platform Docs

Deployment Callback

POST
/api/internal/agents/deployment-callback
curl --request POST \
  --url https://example.com/api/internal/agents/deployment-callback \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "event": "example", "payload": {} }'

Receive a deployment lifecycle event from a GitHub workflow or Databricks job.

Example — mark artifact generation started (call at top of generate-artifacts workflow job): POST /api/internal/agents/deployment-callback Authorization: Bearer <NEXA_SERVICE_AUTH_TOKEN> { “event”: “artifact_generation.started”, “payload”: { “agent_name”: “my-agent”, “version”: “v1”, “github_workflow_run_id”: “12345678”, “github_workflow_run_url”: “https://github.com/org/repo/actions/runs/12345678”, “validation_run_id”: “550e8400-e29b-41d4-a716-446655440000” } } → { “success”: true, “event”: “artifact_generation.started”, “result”: { “generation_id”: “…” } }

Example — mark deployment started (call at top of deploy workflow job): { “event”: “deployment.started”, “payload”: { “agent_name”: “my-agent”, “version”: “v1”, “github_workflow_run_id”: “12345679”, “artifact_generation_id”: “…”, “slack_enabled”: false, “streamlit_enabled”: true } } → { “success”: true, “event”: “deployment.started”, “result”: { “history_id”: “…” } }

Example — per-component update (call after each component step): { “event”: “deployment.component_update”, “payload”: { “agent_name”: “my-agent”, “version”: “v1”, “history_id”: “…”, “component”: “agent_endpoint”, “status”: “deployed” } }

Example — mark deployment done (call at end of deploy workflow): { “event”: “deployment.completed”, “payload”: { “agent_name”: “my-agent”, “version”: “v1”, “history_id”: “…”, “agent_url”: “https://…” } }

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
DeploymentCallbackRequest

Single-envelope request for all deployment lifecycle events.

The event field determines which fields in payload are required.

Events and their required payload fields:

artifact_generation.started agent_name, version optional: environment, agent_id, validation_run_id, github_workflow_run_id, github_workflow_run_url, triggered_by

artifact_generation.completed agent_name, version, generation_id, git_branch, git_commit_sha, file_paths optional: environment, git_commit_url

artifact_generation.failed agent_name, version, generation_id, error_message optional: environment

deployment.started agent_name, version, github_workflow_run_id optional: environment, agent_id, github_workflow_run_url, github_workflow_name, github_commit_sha, artifact_generation_id, artifact_commit_sha, triggered_by, retry_component, agent_url, streamlit_url, slack_url, traces_url, slack_enabled, streamlit_enabled

deployment.component_update agent_name, version, history_id, component, status component: agent_endpoint | streamlit | slack status: deploying | deployed | failed | not_enabled optional: environment, status_reason

deployment.completed agent_name, version, history_id optional: environment, agent_url, streamlit_url, slack_url, traces_url

deployment.failed agent_name, version, history_id, error_message optional: environment, failed_component

automation_deployment.started automation_alias, github_workflow_run_id optional: environment, github_workflow_run_url, github_commit_sha, triggered_by

automation_deployment.completed automation_alias optional: environment, job_id, job_url, git_commit_sha

automation_deployment.failed automation_alias, error_message optional: environment

object
event
required
Event

Lifecycle event type, e.g. ‘deployment.started’

string
payload
required
Payload

Event-specific data

object
key
additional properties
any
Examplegenerated
{
  "event": "example",
  "payload": {}
}

Responses

Section titled “Responses”

200

Section titled “200”

Successful Response

Media typeapplication/json
DeploymentCallbackResponse
object
success
required
Success
boolean
event
required
Event
string
result
required
Result
object
key
additional properties
any
Examplegenerated
{
  "success": true,
  "event": "example",
  "result": {}
}

422

Section titled “422”

Validation Error

Media typeapplication/json
HTTPValidationError
object
detail
Detail
Array<object>
ValidationError
object
loc
required
Location
Array
msg
required
Message
string
type
required
Error Type
string
input
Input
ctx
Context
object
Examplegenerated
{
  "detail": [
    {
      "loc": [
        "example"
      ],
      "msg": "example",
      "type": "example",
      "input": "example",
      "ctx": {}
    }
  ]
}