API Tokens & Webhooks

Use the REST API to read or change workspace data and webhooks to notify another system about supported events. API Access and Webhooks are separate plan features; management also requires manage_workspace_settings.

Create an API Token

1. Select the intended workspace.
2. Open Workspace Settings > API Tokens.
3. Create a token with a descriptive name.
4. Copy the token immediately; its full value is shown only at creation.
5. Store it in your integration's secret configuration.

Tokens are tied to the creating user and workspace, include API read/write abilities, and expire after one year. The current creation form accepts a name; it does not offer a custom scope picker. The API still applies the relevant endpoint access checks.

The token list shows information such as expiry and last use. Revoke individual tokens or all your tokens for that workspace when they are no longer needed.

Call the API

Use the /api/v1 routes on the AgencyPro API host configured for your integration. Send the token in Authorization: Bearer <token> and request JSON responses. Use the documented team or client endpoint for the intended operation; do not assume browser-page URLs are API endpoints.

A valid token alone does not guarantee access: workspace membership, verified account requirements, permissions, an active workspace subscription, and API plan access can also apply. Handle validation, authorization, and rate-limit errors in your integration.

Create a Webhook

1. Open Workspace Settings > Webhooks.
2. Add a webhook with a name and destination URL.
3. Select the events your receiver handles.
4. Set it active and save.
5. Use Send test and check the result at your receiver.

The page lists event subscriptions and delivery statistics, including successful/failed counts and success rate. Edit the destination or events, disable a webhook temporarily, or delete it when no longer needed.

Available events include client.created, request.created, request.updated, request.status_changed, request.completed, invoice.created, and invoice.paid. Use the event selector for the full list rather than inventing event names such as payment.completed.

Handle Deliveries

Webhooks send JSON with entity fields and metadata at the root: _event_id, _event, _created, _created_at, and _workspace_id. Use _event_id to avoid processing a retry twice. Return a successful HTTP response promptly and handle longer work separately.

When a signing secret is configured, requests include X-Webhook-Signature in the form sha256=<HMAC>. The current signer hashes the JSON payload using SHA-256 and JSON encoding with unescaped slashes. Match that serialization when implementing verification and compare signatures safely. Check the actual signed test payload before deploying the receiver.

Failed deliveries are retried according to the webhook configuration. The standard settings page shows statistics and a test action; it does not offer a manual retry button or a full delivery-payload inspector. Use the supported API delivery endpoints when building more detailed monitoring.

MCP Integrations

The companion AgencyPro MCP server uses an AgencyPro API token and configured base URL. Its source includes a local server and an HTTP wrapper exposing /mcp; using the HTTP wrapper requires a deployed endpoint. Availability in an AI client depends on that deployment and the client's integration setup.

Troubleshooting

• API rejected: Check token expiry, workspace, account permissions, subscription state, and plan access.
• No webhook delivery: Confirm the webhook is active, its event is selected, and the destination is reachable.
• Test failed: Check receiver logs, HTTP status, and response time.
• Signature mismatch: Check the signing secret and exact JSON serialization used by the signer.