Skip to main content
Connect engineering events to Costory so you can correlate cost changes with GitHub deploys, CI/CD runs, provider commitments, and custom API events. This makes root cause analysis faster and gives your team shared context in the Cost Explorer.
Events show up as timeline markers in Costory. You can filter by source, category, and labels to explain cost changes in seconds.
Cost chart with event markers for deploys, incidents, and provider changes

​
Supported event sources

GitHub deploys

Pull request merges, releases, and deployment metadata.

CI/CD pipelines

Post build and deploy events directly from your pipelines.

Custom API events

Send any event that explains spend via the Events API.

Provider events

AWS live; Azure and GCP on the roadmap.

​
How events work in Costory

  1. Connect a source (GitHub, CI/CD, or API).
  2. Categorize events as BUSINESS, TECHNICAL, or PROVIDER.
  3. Overlay events on cost charts for fast in the Cost Explorer.
  4. Share context in saved views and Slack reports.

​
Event categories

Costory groups events into three categories so you can filter consistently across teams:
CategoryWhat it representsExamples
BUSINESSGo-to-market or product eventsLaunches, pricing changes, marketing campaigns
TECHNICALEngineering and infrastructure changesDeploys, incidents, migrations, CI/CD runs
PROVIDERCloud provider and billing changes purchases, activations, price changes

​
Connect GitHub events

Use the GitHub integration to capture deploys, PR merges, and releases.
1

Open Events setup

In Costory, go to Setup -> Events.
2

Connect GitHub

Click Connect GitHub to start the OAuth flow, then authorize the Costory GitHub App for the organization or repositories you want to track.
3

Approve permissions

Costory requests read-only access to repository metadata, pull requests, deployments, and releases. Webhooks are used to deliver events in near real time.
If your organization uses GitHub Enterprise, confirm that outbound webhooks can reach Costory and that the GitHub App is allowed by your org policy.

​
Example: curl from a CI / CD pipeline

curl -X POST "https://app-api.costory.io/events" \
  -H "Authorization: Bearer $COSTORY_EVENTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Deploy complete",
    "timestamp": "2026-03-04T14:25:00Z",
    "category": "TECHNICAL",
    "source": "ci-cd",
    "environment": "prod",
    "service": "api",
    "labels": ["release", "backend"],
    "metadata": {
      "commit": "1b2c3d4",
      "pipeline": "github-actions",
      "url": "https://github.com/acme/api/actions/runs/123"
    }
  }'
FieldRequiredDescription
nameYesEvent title shown in the timeline.
timestampYesISO-8601 UTC timestamp for the event.
categoryYesBUSINESS, TECHNICAL, or PROVIDER.
sourceYesA short identifier like custom, ci-cd, or github.
environmentNoprod, staging, or another environment label.
serviceNoService or application name.
labelsNoReusable tags for filtering in Costory.
metadataNoJSON object with URLs, commit SHAs, or context.
Use consistent labels and environments so filters work across teams. For example: prod, staging, api, frontend.

​
Example: Python

import os
import requests

payload = {
    "name": "Incident: cache saturation",
    "timestamp": "2026-03-04T18:42:00Z",
    "category": "TECHNICAL",
    "source": "custom",
    "environment": "prod",
    "service": "cache",
    "labels": ["incident", "cache"],
    "metadata": {
        "pagerduty_id": "P123456",
        "url": "https://status.acme.com/incidents/123"
    },
}

response = requests.post(
    "https://app-api.costory.io/events",
    headers={
        "Authorization": f"Bearer {os.environ['COSTORY_EVENTS_API_KEY']}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=10,
)

response.raise_for_status()
For the latest auth headers and endpoint versions, see the Events API docs.

​
Provider events

Provider events are generated automatically once your cloud billing data is connected. Costory currently supports AWS provider events.

Commitment lifecycle

Track and purchases and expirations.

Marketplace renewals

See when third-party subscriptions renew or change.

SKU price changes

Track cloud provider pricing updates over time.

​
Frequently asked questions

GitHub and provider events typically appear within minutes. API events appear as soon as they are accepted by the Events API.
Yes. Post events with historical timestamps and Costory will place them on the correct date in your cost timeline.
No. Events are metadata overlays only. They help explain costs but do not modify billing data.
Yes. Use category, label, source, and environment filters in the Events page and in Cost Explorer views.

​
Next steps

Add Usage Metrics

Combine events with KPIs for full context.

Explore Cost Explorer

See how events drive cost changes in your dashboards.
Last modified on March 4, 2026