Webhooks & API

concorbit provides webhooks for real-time event notifications and a REST API with token-based authentication for programmatic access. This page covers both features.

Webhooks URL: /settings/webhooks
Required permission: webhooks.manage

API Tokens URL: /settings/api-tokens
Required permission: api.tokens

Webhooks

Webhooks let concorbit push real-time notifications to your external systems whenever something happens in your workspace. Instead of polling the API, your server receives an HTTP POST request the moment an event occurs.

Accessing Webhooks

1. Go to Settings from the sidebar.

2. Click the Webhooks card (described as "Outgoing webhook endpoints and delivery logs").

Creating a Webhook

1. Click Add webhook in the top-right corner.

2. Fill in the form:

1. Click Create webhook.

Available Webhook Events

concorbit fires webhook events for all major entities and actions. Event names follow the pattern entity.action. Common events include:

CRM Events:

• contact.created, a new contact was added

• contact.updated, a contact's details were changed

• contact.deleted, a contact was deleted

• company.created, company.updated, company.deleted

• deal.created, deal.updated, deal.deleted, deal.won, deal.lost

• task.created, task.completed

• appointment.created, appointment.updated

Billing Events:

• invoice.created, invoice.sent, invoice.paid, invoice.overdue

• credit_note.created

• subscription.created, subscription.cancelled

• payment.received, payment.failed

Email Events:

• campaign.sent, campaign.opened, campaign.clicked

• email.bounced, email.complained

Vault Events:

• vault.secret_created, vault.secret_accessed, vault.secret_revealed

Portal Events:

• portal.user_invited, portal.user_logged_in

System Events:

• user.invited, user.joined, user.deactivated

• webhook.failing, sent when a webhook endpoint starts failing

The exact list of available events may expand as new features are added.

Webhook Payload Format

Each webhook delivery sends a JSON POST request to your URL with this structure:

{
  "event": "contact.created",
  "timestamp": "2026-04-12T14:30:00Z",
  "tenant_id": "uuid",
  "data": {
    "id": "uuid",
    "name": "Jane Smith",
    "email": "jane@example.com",
    ...
  }
}

The data field contains the full entity payload relevant to the event.

Managing Webhooks

The webhook list shows each endpoint with:

• URL: the destination endpoint.

• Events: the subscribed event names.

• Status badge: Active or Paused.

Actions per webhook:

Webhook Delivery and Retry

When an event fires:

1. concorbit sends an HTTP POST to your URL with the JSON payload.

2. Your server should respond with a 2xx status code within 30 seconds.

3. If the request fails (network error, timeout, or non-2xx response), concorbit retries with exponential backoff.

4. After multiple consecutive failures, the webhook is marked as failing and you receive a webhook.failing notification.

Best practices for your webhook receiver:

• Respond with 200 OK as quickly as possible. Do heavy processing asynchronously.

• Implement idempotency, the same event may be delivered more than once during retries.

• Use HTTPS endpoints only.

Testing Webhooks

To test your webhook integration:

1. Use a tool like webhook.site or RequestBin to create a temporary receiving URL.

2. Create a webhook in concorbit pointing to that URL.

3. Perform the action in concorbit that triggers the event (e.g., create a contact).

4. Check the receiving tool to see the payload.

API Tokens

API tokens provide programmatic access to the concorbit REST API. Each token is a personal access token tied to your user account and carries only the abilities (scopes) you explicitly grant it. The token can never exceed the permissions you hold yourself, and you can scope it down further to just the endpoints it needs.

Accessing API Tokens

1. Go to Settings from the sidebar.

2. Click the API Tokens card (described as "Manage personal access tokens for the API").

Creating a Token

1. Click Create token in the top-right corner.

2. Enter a Token name that describes its purpose (e.g., "CI/CD Pipeline", "Zapier Integration", "Mobile App").

3. Choose an Expires in window from the dropdown (defaults to 90 days).

4. Under Abilities, tick the scopes the token needs. A token can only call API endpoints whose ability it carries, so pick the minimum set. At least one ability must be selected before the Generate button enables.

5. Click Generate token.

6. Important: Copy the token immediately. It is displayed only once and cannot be retrieved later. Store it securely (e.g., in a password manager or environment variable).

The token is shown in a highlighted box with a "Copy" indicator. Click Dismiss to close the display.

Token List

The token list shows all your active tokens with:

• Name: the label you gave the token.

• Last used: how recently the token was used (e.g., "2h ago", "3d ago", "Never").

• Expires: the expiration date, if set.

Revoking a Token

1. Click Revoke next to the token you want to disable.

2. The token is immediately invalidated. Any API requests using it will receive a 401 Unauthorized response.

Revocation is permanent. If you need access again, create a new token.

API Authentication

Include your token in the Authorization header of every API request:

Authorization: Bearer your-token-here

Example using curl:

curl -H "Authorization: Bearer your-token-here" \
     -H "Accept: application/json" \
     https://app.concorbit.com/api/contacts

API Rate Limits

The concorbit API enforces rate limits to ensure fair usage:

• Standard limit: 300 requests per minute per token.

• Burst allowance: Short bursts above the limit are tolerated, but sustained excess triggers throttling.

• Response headers: Every API response includes rate limit headers:

  • X-RateLimit-Limit, your per-minute limit.

  • X-RateLimit-Remaining, requests remaining in the current window.

  • Retry-After, seconds to wait before retrying (present only when throttled).

When throttled, the API returns HTTP 429 (Too Many Requests). Your integration should respect the Retry-After header and back off.

API Security Best Practices

• Never expose tokens in client-side code (JavaScript, mobile apps with decompilable source). Use a backend proxy.

• Use separate tokens for separate integrations. If one is compromised, you can revoke it without affecting others.

• Rotate tokens periodically. Create a new token, update your integration, then revoke the old one.

• Audit token usage. Check the "Last used" timestamp regularly. Revoke tokens that have not been used recently.

Related Documentation

• Roles & Permissions. An API token can never exceed the creating user's permissions, and is further scoped to the abilities you grant it.

• Audit Log. API actions are logged in the audit trail.

• Security & Authentication, securing your account that owns the tokens.