Webhooks

Assimetria OS receives inbound webhooks from external services to trigger automated workflows. These endpoints are public (no Bearer token required) but use service-specific signature verification.

GitHub webhooks

Receive push events from GitHub repositories. Used for automated logo regeneration, template sync, and deployment triggers.

Endpoint

POST https://api.orkosi.com/api/webhooks/github

Configuration

In your GitHub repository settings, add a webhook with:

Field	Value
Payload URL	https://api.orkosi.com/api/webhooks/github
Content type	application/json
Secret	Your webhook secret (configured in Settings > Credentials)
Events	push

Signature verification

GitHub signs each payload with an HMAC-SHA256 signature in the X-Hub-Signature-256 header. Assimetria OS verifies this signature before processing the event.

Supported events

Event	Trigger	Action
push to main	Code merged to main branch	Triggers deployment pipeline
push (logo files)	Logo asset changes	Auto-regenerates brand assets

Stripe webhooks

Receive billing events from Stripe for credit purchases, subscription changes, and payment failures.

Endpoint

POST https://api.orkosi.com/api/webhooks/stripe

Configuration

In the Stripe Dashboard > Webhooks, add an endpoint with:

Field	Value
Endpoint URL	https://api.orkosi.com/api/webhooks/stripe
Events	checkout.session.completed, invoice.paid, invoice.payment_failed, customer.subscription.updated, customer.subscription.deleted

Signature verification

Stripe signs payloads using the webhook signing secret. The raw request body is verified against the Stripe-Signature header using the Stripe SDK.

Handled events

Event	Action
checkout.session.completed	Credits deposited to user account
invoice.paid	Subscription renewal recorded
invoice.payment_failed	Account flagged, notification sent
customer.subscription.updated	Tier updated (Pro, Teams, Enterprise)
customer.subscription.deleted	Subscription cancelled, downgrade to Free

Railway webhooks

Receive deployment status notifications from Railway.

Endpoint

POST https://api.orkosi.com/api/webhooks/railway

Supported events

Event	Action
deployment.completed	Updates deploy status in dashboard
deployment.failed	Creates alert, notifies team

Customer chat webhooks

Receive inbound messages from messaging platforms (Telegram, WhatsApp) for customer support workflows.

Endpoint

POST https://api.orkosi.com/api/webhooks

Supported platforms

Platform	Setup
Telegram	Configure bot webhook URL via BotFather
WhatsApp	Configure in Meta Business Suite > Webhooks

Tenant webhook configuration

Organizations can configure custom outbound webhook URLs for events within their tenant. Manage webhook settings via:

curl -X PATCH https://api.orkosi.com/api/tenant-config \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "webhooks": {
      "task_completed": "https://your-app.com/hooks/task-done",
      "agent_error": "https://your-app.com/hooks/agent-alert"
    }
  }'

Security

• All webhook endpoints verify signatures from their respective services before processing.
• Webhook payloads are logged for debugging but sensitive fields are redacted.
• Failed signature verification returns 401 Unauthorized.
• Replay protection: events with timestamps older than 5 minutes are rejected.

Endpoints summary

Method	Path	Auth	Description
POST	/webhooks/github	Signature	GitHub push events
POST	/webhooks/stripe	Signature	Stripe billing events
POST	/webhooks/railway	Signature	Railway deploy events
POST	/webhooks	Signature	Customer chat messages