---
updatedAt: 2026-09-26T17:44:57.000Z
agentTools:
  projectIndex: https://developer.ironcladapp.com/llms.txt
---

# 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 **7 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:

```json
{
  "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](https://developer.ironcladapp.com/reference/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 7-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 7-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

* [Webhook Retries](https://developer.ironcladapp.com/docs/webhooks#retries) - Learn about Ironclad's retry mechanism
* [Update a Webhook](https://developer.ironcladapp.com/reference/update-a-webhook) - API reference for modifying webhook status
* [Webhook Verification](https://developer.ironcladapp.com/reference/webhook-verification) - Ensure webhook authenticity
* [Webhook Authentication](https://developer.ironcladapp.com/reference/webhook-authentication) - Secure your webhook endpoints