GuidesAPI ReferenceRecipes
API Reference
Request a Demo
Start typing to search…

Webhook Deactivation

Understand how Ironclad automatically disables consistently failing webhooks to protect your integrations

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

  1. Set up alerts: Subscribe to error dashboard notifications to be notified immediately when webhooks are disabled
  2. Regular health checks: Periodically review your webhook status via the API to identify potential issues before automatic deactivation
  3. 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:

  1. Via API: Use the Update a Webhook endpoint to change the status back to enabled
  2. 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