API Platform and Webhooks

The API Platform lets developers and advanced teams connect AstraTalk data and events to their own tools. Use it to create scoped API keys, monitor usage, and send signed webhook events to systems you control.

Create an API Key

1. Open Dashboard > API Platform.
2. Choose the key environment: sandbox for testing or production for live integrations.
3. Select only the scopes your integration needs.
4. Create the key and store the raw key immediately.

AstraTalk shows the raw key only once. After that, only the prefix is visible so your account is protected if someone opens the dashboard later.

Monitor Quotas

Each key card shows monthly usage, remaining calls, and a quota health label:

• Healthy means the key is comfortably under quota.
• Watch means usage is rising and should be monitored.
• Critical means the key is close to its monthly limit.
• Exhausted means new API calls are blocked until quota resets or the limit is changed.

When a key exceeds its monthly quota, AstraTalk returns HTTP 429 with MONTHLY_QUOTA_EXCEEDED and rate-limit headers so your integration can back off cleanly.

Rotate or Revoke a Key

• Rotate a key when you believe it may have been exposed or when your team is changing credentials.
• Revoke a key when an integration should no longer access AstraTalk.
• Update your integration with the new raw key before removing the old one from your own secret manager.

Configure a Webhook Endpoint

1. Open the Webhooks tab.
2. Add an HTTPS endpoint URL.
3. Choose the events your system should receive.
4. Store the signing secret shown after creation.
5. Use Test Delivery to confirm your endpoint receives a signed request.

Each webhook request includes an event header and an HMAC signature header so your server can verify it came from AstraTalk.

Build a Custom Connector

Use the Wizard tab when you need a reusable connector instead of a single webhook endpoint.

1. Choose the connector type, such as outbound webhook, custom REST API, scheduled poller, OAuth connector, or encrypted secret entry.
2. Select the auth template: HMAC signature, bearer token, API key header, basic auth, no auth, or OAuth approval.
3. Pick the AstraTalk events the connector should handle.
4. Choose a payload mapping template and whether redacted user context should be included.
5. Save the connector, then use Test to send a signed sample payload for deliverable webhook and REST connectors.

Connector secrets are encrypted server-side, raw values are not shown again after save, and test/replay attempts are written to connector run logs.

Embed Micro-Rituals

Approved partners can embed AstraTalk micro-rituals through the v1 partner API:

• GET /api/v1/rituals lists available micro-rituals.
• GET /api/v1/rituals/:id returns one micro-ritual.
• GET /api/v1/rituals/recommended returns a time-aware recommendation.

Send your key in the X-API-Key header. Browser embeds must use an allowed origin configured for the partner app, such as https://example.com. Origins are exact scheme/host/port values, not full page URLs.

Every authenticated response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. If an embed exceeds its daily route limit, AstraTalk returns HTTP 429 with RATE_LIMIT_EXCEEDED and Retry-After.

Manage Connectors

Connector cards in the Wizard tab include lifecycle controls:

• Use Test to send a signed sample payload for deliverable webhook and REST connectors.
• Use Rotate secret when a credential changes or may have been exposed.
• Use Disable to pause delivery without deleting configuration.
• Use Enable to resume an active, non-OAuth connector.
• Use Delete to remove a connector and its run history.

Review and Replay Deliveries

Recent webhook attempts appear under each endpoint. Each row shows the event, delivery status, HTTP response, latency, and any error message.

Use Replay to resend a recent delivery after fixing an endpoint or validating a downstream workflow. Replay creates a new delivery log entry and includes replay metadata in the payload.

Connector runs in the Wizard tab can also be replayed. Replays create a new run log and include replay metadata in the outgoing payload.

Review the Audit Trail

The Audit tab records key creation, rotation, revocation, webhook changes, test deliveries, and replays. Audit rows are stored server-side and show the action, outcome, resource type, and timestamp without exposing raw API keys or webhook secrets.

Safety Tips

• Never paste API keys or webhook secrets into chat, issue trackers, or plain text documents.
• Use separate sandbox and production keys.
• Give each integration the smallest scope set it needs.
• Rotate connector secrets after team or vendor access changes.
• Revoke unused keys and endpoints.
• Check delivery failures before assuming an automation did not run.

Troubleshooting

Issue	What to Check
API calls return unauthorized	Confirm the key is active, copied correctly, and using the expected environment.
Browser embed is blocked	Confirm the website origin exactly matches the allowed origin configured for that partner app.
API calls return monthly quota exceeded	Check the key card's monthly quota status and reduce traffic or rotate traffic to an appropriately provisioned key.
Micro-ritual calls return rate limited	Check the daily route headers and retry after the X-RateLimit-Reset timestamp.
Webhook test returns no response	Confirm the endpoint is public HTTPS, accepts POST requests, and responds within the timeout.
Webhook signature fails	Confirm your server signs the exact raw request body with the endpoint signing secret.
Replay keeps failing	Open the latest delivery row and inspect the HTTP status or error message.
Connector URL is rejected	Use a public HTTPS URL. Localhost and private-network hosts are blocked for safety.
Audit row is missing	Refresh the Audit tab after the operation completes.