API Integration

Webhooks & Event Subscriptions

Receive real-time notifications when events happen in your TaoApex account. Integrate seamlessly with your systems using secure webhook endpoints.

What Are Webhooks?

Webhooks allow you to receive real-time HTTP notifications when specific events occur in your TaoApex account. Instead of polling our API for updates, TaoApex will push data to your endpoint the moment something happens. This enables instant integrations with your internal systems, databases, and workflows.

Supported Event Types

Subscribe to the events that matter most for your integration. Each event type includes a structured payload with all relevant information.

message.created

Triggered when a new message is created

message.updated

Triggered when a message is updated or edited

session.started

Triggered when a new conversation session begins

session.ended

Triggered when a conversation session ends

file.uploaded

Triggered when a file is uploaded to a conversation

user.subscribed

Triggered when a user subscribes to a plan

Payload Structure

Every webhook delivery includes a JSON payload with standardized fields. The data object contains event-specific information.

{
  "id": "evt_xxxxxxxxxxxx",
  "type": "message.created",
  "timestamp": "2026-07-19T12:00:00Z",
  "data": {
    "message_id": "msg_xxxxxxxxxxxx",
    "user_id": "usr_xxxxxxxxxxxx",
    "content": "...",
    "model": "claude-sonnet-4-20250514"
  }
}

Security

TaoApex webhooks are designed with security as a top priority. All webhook communications are encrypted and verified.

HMAC Signatures

Each webhook includes an HMAC-SHA256 signature in the X-TaoApex-Signature header. Verify this signature to ensure the request came from TaoApex.

TLS Encryption

All webhook deliveries use HTTPS/TLS 1.2+ to ensure data is encrypted in transit.

Delivery & Retries

TaoApex guarantees at-least-once delivery for all webhook events. If your endpoint fails to respond with a 2xx status code, we will retry with exponential backoff.

200Success: Webhook delivered successfully

4xx/5xxRetry: Delivery will be retried with backoff

Frequently Asked Questions

What is the timeout for webhook endpoints?

Your webhook endpoint must respond within 30 seconds. If your processing takes longer, acknowledge receipt immediately with a 200 status and process asynchronously.

How do I verify webhook signatures?

Each webhook includes an X-TaoApex-Signature header. Compute the HMAC-SHA256 of the raw request body using your webhook secret and compare it to the header value.

What happens if my endpoint is temporarily unavailable?

TaoApex automatically retries failed deliveries with exponential backoff: after 1 minute, 5 minutes, 30 minutes, 2 hours, and 12 hours. After 5 failed attempts, the event is marked as failed.

Can I receive webhooks for specific events only?

Yes. When configuring your webhook endpoint, you can select which event types you want to subscribe to. You will only receive notifications for those events.

Is there a limit on webhook deliveries?

TaoApex supports up to 100 webhooks per account with a maximum of 1,000 deliveries per minute across all endpoints. Contact us if you need higher limits for enterprise use cases.

Ready to integrate?

Start receiving real-time events from TaoApex. Set up your webhook endpoint in minutes.

Get API Access