canonical: https://jentic.com/apis/bill.com/bill-connect-events-api

# BILL Connect Events API

Jentic publishes the only available OpenAPI specification for BILL Connect Events API, keeping it validated and agent-ready. Connect Events lets developers subscribe to push notifications about BILL platform activity - bill creation, approval state changes, vendor updates, and similar - through a dedicated v3 subscription model. The API exposes the event catalog, subscription lifecycle (create, read, list, update, patch, delete), security key rotation, a test-fire endpoint, and a per-subscription event delivery endpoint. It is the BILL equivalent of webhooks for downstream systems that need to react in near real time.

## For AI agents

Subscribe to BILL platform events, manage webhook subscriptions, rotate security keys, and trigger test-event delivery for verification.

## Scope

Does not handle bill creation, approvals, or AR customer management directly - use only for BILL event subscription, signing-key rotation, and test-event delivery.

## Capabilities

- List the event types available to subscribe to via /v3/events/catalog
- Create a subscription for one or more event types with /v3/subscriptions
- Read, update, patch, or delete an existing subscription
- Rotate the subscription's security key via /v3/subscriptions/{subscriptionId}/security_key
- Trigger a test-event delivery against a subscription endpoint with /v3/subscriptions/{subscriptionId}/test
- Fetch a specific subscription detail through /v3/events/subscription/{subscriptionId}
- Send an event to a subscription's endpoint via /v3/events/subscription/{subscriptionId}/event/{eventId}

## Use cases

### Real-Time Approval Notifications

Downstream systems - Slack alerters, ERP syncs, or finance dashboards - react when bills move through the BILL approval workflow. The integration creates a subscription via POST /v3/subscriptions on the relevant event types from /v3/events/catalog, then receives signed callbacks at its registered URL. /v3/subscriptions/{subscriptionId}/security_key rotates the signing key as part of routine credential hygiene.

Example prompt: Call POST /v3/subscriptions with the destination URL and the bill-approved eventType from /v3/events/catalog, then verify with /v3/subscriptions/{subscriptionId}/test

### Subscription Lifecycle Management

Operations teams keep BILL event subscriptions in sync with downstream consumers - adding new ones, retiring old ones, and PATCHing URLs when an internal service moves. The full CRUD surface (POST, GET, PUT, PATCH, DELETE on /v3/subscriptions/{subscriptionId}) supports this without manual UI clicks. /v3/health confirms the Connect Events plane is reachable before bulk lifecycle changes.

Example prompt: Call /v3/health, then PATCH /v3/subscriptions/{subscriptionId} with the new destination URL when a downstream service moves

### Endpoint Verification Before Go-Live

Before flipping a webhook subscription live, integrators verify the destination URL accepts BILL's payload signing and returns 2xx within the timeout. POST /v3/subscriptions/{subscriptionId}/test fires a synthetic event so engineers can inspect logs and confirm the endpoint is wired correctly. This catches bad URL config, missing TLS, and signature-verification mistakes before any real event traffic flows.

Example prompt: Call POST /v3/subscriptions/{subscriptionId}/test, then inspect destination logs to confirm the test event arrived signed and a 2xx was returned

### Agent-Driven Webhook Setup via Jentic

An AI agent provisioning a new BILL integration searches Jentic for 'subscribe to BILL events', loads the subscription create operation, and executes it with a destination URL the user provides. The Connect Events credential sits in Jentic's vault, so the agent never sees the raw key, and the test endpoint is then loaded and executed automatically to verify the round-trip. End-to-end webhook setup becomes a single agent prompt.

Example prompt: Search Jentic for 'subscribe to BILL events', load POST /v3/subscriptions and execute, then load /v3/subscriptions/{subscriptionId}/test and execute to verify

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | /v3/events/catalog | List available event types |
| POST | /v3/subscriptions | Create a new event subscription |
| GET | /v3/subscriptions | List all subscriptions |
| PATCH | /v3/subscriptions/{subscriptionId} | Patch fields on a subscription |
| DELETE | /v3/subscriptions/{subscriptionId} | Delete a subscription |
| POST | /v3/subscriptions/{subscriptionId}/security_key | Rotate the subscription security key |
| POST | /v3/subscriptions/{subscriptionId}/test | Trigger a test-event delivery |
| GET | /v3/health | Check Connect Events service health |

## Key resources

- **Event Catalog** — List the event types available to subscribe to
- **Subscriptions** — Full CRUD on event subscriptions plus PATCH and DELETE
- **Security Key** — Rotate the signing key for a subscription
- **Test and Health** — Fire test events and check service health
- **Event Delivery** — Per-subscription event delivery endpoints

## Why Jentic

- **Setup:** Wiring the BILL Connect Events API by hand means carrying gateway credentials on every call, tracking per-subscription security keys, and building each subscription path yourself against the connect-events host. Through Jentic you install once, import BILL Connect Events from the API Directory, store the credentials once, and your agent calls it.
- **Permission scoping:** Connect Events puts the subscription id in the URL path (/v3/subscriptions/{subscriptionId}/...), so a rule can pin your agent to one subscription: it can read that subscription and send test events and nothing else. You choose the operations it may call, so deleting a subscription or rotating its security key is not included unless you add them.
- **Credential handling:** Your BILL gateway credentials and per-subscription security keys are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'subscribe to BILL events' or 'rotate a webhook security key', and Jentic returns the matching Connect Events operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **BILL Authentication API** — Provides the session credentials Connect Events depends on
- **BILL Approvals API** — Source of approval state-change events that Connect Events publishes
- **BILL Customer Management API** — Source of customer change events that Connect Events publishes

## FAQ

### Why is there no official OpenAPI spec for BILL Connect Events API?

BILL documents Connect Events in narrative form on developer.bill.com but does not publish the underlying OpenAPI document. Jentic generates and maintains a structured OpenAPI specification so AI agents and developers can call BILL Connect Events API via tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the BILL Connect Events API use?

Connect Events runs through BILL's gateway and is authenticated with a BILL developer key plus session credentials, matching the rest of the BILL platform. Inbound delivery to your webhook URL is signed with the per-subscription security key returned at create time. Through Jentic, both sides of the credential are held in the vault.

### How do I subscribe to bill-approved events?

Call GET /v3/events/catalog to find the event-type identifier for bill-approved, then POST /v3/subscriptions with that event type and your destination URL. Verify with POST /v3/subscriptions/{subscriptionId}/test before going live.

### What are the rate limits for the BILL Connect Events API?

Rate limits inherit from the BILL gateway and are not published per-endpoint. For high-cardinality fan-out, prefer fewer subscriptions with multiple event types over many narrowly scoped subscriptions, and consume the events asynchronously on the receiving side.

### How do I rotate a subscription's security key?

POST /v3/subscriptions/{subscriptionId}/security_key returns a new signing key and immediately retires the previous one. Make sure your verification code accepts both keys for a brief overlap window if your delivery pipeline can have in-flight events when rotation runs.

### How do I subscribe to BILL events through Jentic?

Run `pip install jentic`, then `await client.search('subscribe to BILL events')`, `await client.load(...)` for POST /v3/subscriptions, and `await client.execute(...)` with the event-type and destination URL. Chain into /v3/subscriptions/{subscriptionId}/test to fire a synthetic event for verification.

### Can I limit what my agent is allowed to do with the BILL Connect Events API?

Yes. Because you run Jentic One yourself, your own rules decide which Connect Events operations and credentials the agent may use. Since the subscription id sits in the URL path (/v3/subscriptions/{subscriptionId}/...), you can pin the agent to a single subscription and allow only the calls you approve, such as reading that subscription and firing a test event with POST /v3/subscriptions/{subscriptionId}/test. Destructive actions like DELETE /v3/subscriptions/{subscriptionId} or rotating the security key stay off the table unless you explicitly grant them.