Webhook Deactivation

Ironclad automatically monitors webhook delivery success and will disable webhooks that consistently fail over a specified period. This automatic deactivation feature helps protect your integrations by preventing unnecessary traffic to non-responsive endpoints while ensuring you're notified when issues occur.

How Automatic Deactivation Works

Failure Tracking

Ironclad tracks the delivery status of each webhook request:

Success: When your endpoint responds with a 2xx HTTP status code, the consecutive failure count is reset to zero
Failure: When your endpoint responds with a 4xx or 5xx HTTP status code (except 410), the consecutive failure count is incremented
410 Response: Webhooks that receive a 410 (Gone) response are immediately disabled, as this indicates the endpoint is permanently unavailable

Deactivation Criteria

A webhook will be automatically disabled when both of the following conditions are met:

Consecutive Failures: The webhook has failed at least 100 consecutive times
Time Period: These failures have occurred over a minimum of 10 consecutive days with no successful deliveries in between

Status Changes

When a webhook is automatically disabled:

The webhook status field changes from enabled to disabledBySystem
The statusLastUpdatedAt field is updated with the timestamp of the deactivation
The statusLastUpdatedBy field is set to "system"
An error is logged to Ironclad's "Errors" dashboard for monitoring and alerting

Webhook Status Fields

When retrieving webhook information via the API, you'll see several status-related fields:

{
  "id": "webhook_id",
  "status": "enabled",
  "statusLastUpdatedAt": "2025-01-17T17:51:49.008Z",
  "statusLastUpdatedBy": "user_id",
  "consecutiveFailureCount": 0,
  "firstConsecutiveFailure": null,
  // ... other webhook fields
}

Status Field Values

enabled: The webhook is active and will receive events
disabled: The webhook has been manually disabled by a user
disabledBySystem: The webhook has been automatically disabled due to consecutive failures

Failure Tracking Fields

consecutiveFailureCount: Number of consecutive failed deliveries since the last success
firstConsecutiveFailure: Timestamp of when the current sequence of consecutive failures began

Monitoring and Alerting

Error Dashboard Integration

When webhooks are automatically disabled, Ironclad logs detailed information to the "Errors" dashboard. You can:

Subscribe to error notifications to be alerted immediately when a webhook is disabled
View historical deactivation events and failure patterns
Monitor webhook health across your organization

Best Practices for Monitoring

Set up alerts: Subscribe to error dashboard notifications to be notified immediately when webhooks are disabled
Regular health checks: Periodically review your webhook status via the API to identify potential issues before automatic deactivation
Monitor failure counts: Watch for increasing consecutiveFailureCount values as an early warning system

Re-enabling Disabled Webhooks

Manual Re-activation

Once you've resolved the underlying issue causing webhook failures, you can re-enable a disabled webhook:

Via API: Use the Update a Webhook endpoint to change the status back to enabled
Via UI: Navigate to Company Settings → API → Webhooks and enable the webhook

Automatic Reset

When you re-enable a webhook:

The consecutiveFailureCount is reset to 0
The firstConsecutiveFailure is cleared
The webhook will begin receiving events immediately

Integration Considerations

Handling 410 Responses

If your endpoint is permanently unavailable, return a 410 (Gone) status code. This will:

Immediately disable the webhook
Prevent unnecessary retry attempts
Clearly indicate the endpoint should not receive further requests

Graceful Degradation

Design your webhook endpoints to:

Return appropriate HTTP status codes
Handle temporary failures gracefully
Log errors for debugging purposes
Implement proper monitoring and alerting

Example Scenarios

Scenario 1: Temporary Service Outage

Your webhook endpoint experiences a 2-hour outage:

Ironclad attempts delivery and receives 503 responses
Failures are counted, but the 10-day minimum prevents immediate deactivation
Once your service recovers and returns 200 responses, the failure count resets
No automatic deactivation occurs

Scenario 2: Abandoned Endpoint

You decommission a service without updating the webhook:

Webhook requests consistently fail with 404 responses
After 100 consecutive failures without any successful requests within a 10-day period, the webhook is automatically disabled
You receive an error notification about the deactivation
You can either fix the endpoint and re-enable, or delete the webhook

Scenario 3: Endpoint Migration

You're migrating to a new webhook endpoint:

Configure your old endpoint to return 410 responses
The webhook is immediately disabled
Update the webhook configuration with the new URL and re-enable it

Related Documentation