Webhook Management¶

Manage webhook delivery status and filter events for your integration.

Overview¶

Contio provides tools to control webhook delivery. You can enable or disable webhooks for your app, and you can filter which event types are delivered to your endpoint.

Webhook Status¶

How Auto-Disable Works¶

Repeated delivery failures can cause Contio to automatically disable webhook delivery for your app. In the current rollout, auto-disable can happen when either of the following is true:

• 50 webhook deliveries have been abandoned after exhausting retries
• More than 72 hours have passed since the last successful delivery and your app still has webhook failures recorded

When auto-disable happens:

• Contio sets webhook_enabled to false
• Contio attempts to notify the primary contact email for your app
• New events that still pass your filter are recorded with pending status instead of being delivered immediately

You can check the current status with GET /v1/partner/admin/app and inspect the webhook_enabled field.

Checking Webhook Status¶

const app = await admin.getApp();
console.log(app.webhook_enabled); // true or false

curl -H "X-API-Key: $API_KEY" \
     -H "X-Client-ID: $CLIENT_ID" \
     https://api.contio.ai/v1/partner/admin/app

Disabling Webhooks¶

const app = await admin.updateWebhookStatus({ enabled: false });

curl -X PUT \
     -H "X-API-Key: $API_KEY" \
     -H "X-Client-ID: $CLIENT_ID" \
     -H "Content-Type: application/json" \
     -d '{"enabled": false}' \
     https://api.contio.ai/v1/partner/admin/webhook-status

Re-Enabling Webhooks¶

When re-enabling, you must tell Contio how to handle events that were queued while delivery was disabled:

• abandon: discard all backlogged pending deliveries. Use this when your endpoint was down and you do not want older events.
• deliver: leave pending deliveries in the queue for automatic processing on the next cycle. Use this when your endpoint is fixed and you want to receive the backlog.

const redeliverBacklog = await admin.updateWebhookStatus({
  enabled: true,
  pending_disposition: 'deliver'
});

const discardBacklog = await admin.updateWebhookStatus({
  enabled: true,
  pending_disposition: 'abandon'
});

curl -X PUT \
     -H "X-API-Key: $API_KEY" \
     -H "X-Client-ID: $CLIENT_ID" \
     -H "Content-Type: application/json" \
     -d '{"enabled": true, "pending_disposition": "deliver"}' \
     https://api.contio.ai/v1/partner/admin/webhook-status

curl -X PUT \
     -H "X-API-Key: $API_KEY" \
     -H "X-Client-ID: $CLIENT_ID" \
     -H "Content-Type: application/json" \
     -d '{"enabled": true, "pending_disposition": "abandon"}' \
     https://api.contio.ai/v1/partner/admin/webhook-status

Event Filtering¶

Overview¶

Event filtering lets you control which webhook event types are delivered to your endpoint. This is useful when your integration only needs a subset of Contio webhook events.

Filter Types¶

Available Event Types¶

The following event types can be included or excluded. The AsyncAPI Webhook Events Reference is the canonical event catalog.

• meeting.created, meeting.updated, meeting.completed
• action_item.created, action_item.updated, action_item.completed
• automation.assignment.created
• calendar_event.created, calendar_event.updated, calendar_event.deleted
• agenda_item.created, agenda_item.updated, agenda_item.deleted
• participant.added, participant.removed

Setting a Filter¶

const includeFilter = await admin.setWebhookFilter({
  type: 'include',
  events: ['meeting.created', 'meeting.completed', 'action_item.created']
});

const excludeFilter = await admin.setWebhookFilter({
  type: 'exclude',
  events: ['calendar_event.created', 'calendar_event.updated', 'calendar_event.deleted']
});

curl -X PUT \
     -H "X-API-Key: $API_KEY" \
     -H "X-Client-ID: $CLIENT_ID" \
     -H "Content-Type: application/json" \
     -d '{"type": "include", "events": ["meeting.created", "meeting.completed"]}' \
     https://api.contio.ai/v1/partner/admin/webhook-filter

Checking Current Filter¶

const app = await admin.getApp();

if (app.webhook_filter) {
  console.log(`Filter: ${app.webhook_filter.type}`);
  console.log(`Events: ${app.webhook_filter.events.join(', ')}`);
} else {
  console.log('No filter configured — all supported events are delivered');
}

Removing a Filter¶

const app = await admin.removeWebhookFilter();
console.log(app.webhook_filter); // null

curl -X DELETE \
     -H "X-API-Key: $API_KEY" \
     -H "X-Client-ID: $CLIENT_ID" \
     https://api.contio.ai/v1/partner/admin/webhook-filter

Interaction Between Status and Filtering¶

Troubleshooting¶

Webhooks were auto-disabled¶

1. Check that your webhook endpoint is reachable and returns 2xx responses quickly
2. Review recent delivery failures in GET /v1/partner/admin/webhook-deliveries
3. Fix the underlying issue in your endpoint or infrastructure
4. Re-enable webhooks with the appropriate pending_disposition (deliver to replay the backlog or abandon to discard it)
5. Confirm webhook_enabled returns true in GET /v1/partner/admin/app

Events are not being received¶

1. Check whether webhooks are enabled in GET /v1/partner/admin/app
2. Check whether a webhook_filter is configured in the same response
3. Confirm the event type is included by your filter or not excluded by it
4. Remember that user.connection.revoked always bypasses filters

Invalid event types in a filter request¶

If you specify an unsupported event type, the API returns 400 Bad Request and includes the list of valid values in the valid_event_types field.