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 cause Contio to automatically disable webhook delivery for your app. Auto-disable happens when either of the following is true:

• 10 consecutive failed delivery attempts. Every failed HTTP attempt counts, including retries of the same event (a delivery that fails all 3 attempts contributes 3). A single successful delivery resets the count to zero.
• 72 hours without a successful delivery while your app has failures recorded. For an endpoint that has never delivered successfully, the 72 hours are measured from the first failure of the current streak.

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
• partner.idp.domain_verified, partner.idp.domain_verification_failed, partner.idp.domain_revoked

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.