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 webhook events. Each event counts once, on its first failed HTTP attempt; automatic retries of the same event do not add to the count, so the threshold does not depend on the retry schedule. 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
• Deliveries that were still waiting for a retry, and new events that still pass your filter, are recorded with parked status instead of being delivered

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

Parked Events and the Recovery Window¶

While webhook delivery is disabled (manually or by auto-disable), Contio holds matching events as parked deliveries. Parked deliveries are never sent automatically.

• Parked deliveries are recoverable for 7 days, measured from when the event was created (created_at), not from when delivery was disabled.
• Parked deliveries older than 7 days move to expired and are never replayed automatically, even if you re-enable with deliver.
• An expired delivery can still be retried individually with POST /v1/partner/admin/webhook-deliveries/{id}/retry once webhook delivery is enabled again.
• Terminal deliveries (delivered, filtered, abandoned, expired) are purged after 30 days.

Use GET /v1/partner/admin/webhook-deliveries?status=parked to inspect the backlog before re-enabling, and ?status=expired to find events that aged out of the recovery window.

Re-Enabling Webhooks¶

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

• abandon: discard the entire backlog (parked, pending, and failed deliveries). Use this when you do not want older events.
• deliver: release parked deliveries created within the last 7 days for automatic processing on the next cycle, and mark older ones expired. Use this when your endpoint is fixed and you want to receive the recent 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 parked events from the last 7 days or abandon to discard the backlog)
5. Optionally retry individual expired deliveries you still need via POST /v1/partner/admin/webhook-deliveries/{id}/retry
6. 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.