Request

Response

    Event Delivery Guarantees

    This page is the authoritative source for how the Webhooks service delivers events, what it does when a delivery fails, when a webhook stops delivering, and how to get it working again.

    The Delivery Model

    When an event occurs, the Webhooks service finds the webhooks that match it and sends each one a notification as an HTTP POST request to its callback URL. Delivery is asynchronous: the callback is sent after the event has occurred, independently of whatever action caused it, so your app receives it at some point after the fact rather than as part of the original operation.

    Three properties of the model shape how you should build against it:

    • Delivery is at least once. The Webhooks service guarantees that a notification is delivered at least once, which means the same event can arrive more than once. Your callback needs to tolerate a repeat.
    • A delivery must be acknowledged quickly. The Webhooks service expects a 2xx status code within 7 seconds. A non-2xx response, or no response within 7 seconds, is a failed delivery.
    • A webhook only receives events that occur while it can deliver. The webhook must be active or reactivated at the moment the event occurs. An event published before the webhook was created, or while it was inactive, is not delivered to it later.

    For the concepts behind webhooks and callbacks, see Basics. For what your callback server has to do, see Configuring Your Server.

    When a Delivery Fails

    Two different things happen when deliveries fail, and it is worth keeping them apart. One failed event is retried. Repeated failed events deactivate the webhook.

    What failedWhat the Webhooks service does
    A single event Retries that event up to 8 times over the following 48 hours. The webhook stays active throughout.
    Five events in a row Sets the webhook to inactive and stops sending callbacks to it.

    Retrying One Event

    • By default, every event that fails to deliver on the first attempt is retried 8 times over the span of the next 48 hours, in an exponentially delayed fashion.
    • If the event still fails to deliver after all the retry attempts, the Webhooks service records the failure by maintaining a counter against the webhook.

    Repeated Failures Deactivate the Webhook

    • The Webhooks service applies the retry logic above to 5 event types that arrive for the webhook.
    • If all 5 events fail to deliver, the webhook is deactivated by setting its status to inactive.

    A deactivated webhook sends no further callbacks until it is reactivated, and events that occur while it is inactive are not delivered to it afterwards. Because the failure counter is what drives deactivation, a callback that has been down for a while can be deactivated some time after you fix it, if failed events are still working through their retry windows.

    Manual Deactivation During High Fan-Out

    In rare cases of high fan-out — a large volume of matching events for a webhook whose callback URL is not responding as expected — Autodesk may manually deactivate the affected webhook as a safety measure to protect the service, even before the standard retry window above completes. The webhook can be reactivated through the API once the callback is fixed, using the same recovery steps as any other deactivation.

    Webhook States

    The status field of a webhook tells you where it stands.

    StatusWhat caused it, and what it means for you
    active The most recent event notifications were delivered successfully. Nothing to do; callbacks are flowing.
    inactive Five events in a row failed to deliver, or you set the status to inactive yourself. No callbacks are being sent, and events that occur now are lost to this webhook. Fix the callback and reactivate it.
    reactivated The webhook was previously inactive and has been reactivated, either by you or automatically, and no events have occurred since. Callbacks can flow again. The next event decides whether it becomes active or inactive.

    To find webhooks in a given state, filter your list by status. See Retrieve a List of Webhooks. For the field itself, see the Field Guide.

    Recovering an Inactive Webhook

    Reactivating the webhook through the Update a Webhook operation is the recovery path available to you as the owner of the webhook. Work through these steps in order.

    1. Detect the problem. Retrieve the webhook and read its status. A status of inactive means deliveries failed, not that the subscription is misconfigured.
    2. Fix the callback. The webhook was deactivated because delivery attempts failed, so the cause is almost always at your end. Confirm your server is reachable, that it returns a 2xx status code within 7 seconds, and that you are not rejecting callbacks during signature verification. See Configuring Your Server and How to Verify Payload Signature.
    3. Reactivate the webhook. Set status to active using the Update a Webhook operation. When you set this field you can send only active or inactive; reactivated is a value the Webhooks service sets, not one you send.
    4. Verify delivery. Trigger the event again and confirm the callback arrives. Until an event occurs, a reactivated webhook has not yet proved anything.

    Reactivating before fixing the callback only starts the failure count again. Fix first, then reactivate.

    If the webhook has expired rather than been deactivated, it no longer exists and cannot be reactivated. Create a new one.

    Automatic Reactivation

    The Webhooks service can reactivate a webhook for you after it becomes inactive, instead of waiting for you to do it. This is opt-in, and it is separate from the manual recovery above.

    The Flag

    • A webhook with autoReactivateHook set to true becomes a candidate for the automatic reactivation lifecycle. By default the flag is false.
    • You can set the flag when you create the webhook, or later using the Update a Webhook operation.

    The Lifecycle

    For a webhook that has the flag set:

    • After the webhook becomes inactive through the normal retry attempts, the Webhooks service runs a background process that selects webhooks that became inactive between 7 and 30 days earlier and sets their status to reactivated. A webhook inactive for more than 30 days is not picked up by this process and must be recreated.
    • The Webhooks service then accepts one event for the webhook, as a single delivery attempt.
    • If that delivery succeeds, the status becomes active.
    • If it fails, the status returns to inactive and the Webhooks service records the failure against the webhook.
    • The Webhooks service applies this lifecycle 5 times. After that the webhook is made permanently inactive, and autoReactivateHook is set to false on it.

    Automatic reactivation buys you recovery attempts without intervention, but it does not fix a broken callback, and it is finite. A webhook that has been made permanently inactive still needs the manual recovery steps above.

    Designing a Reliable Callback

    • Acknowledge first, process afterwards. Return a 2xx status code as soon as you have accepted the payload, then do your work. Making the Webhooks service wait for your processing risks the 7-second window and turns a slow job into a failed delivery.
    • Make your processing idempotent. Because delivery is at least once, the same event can arrive more than once. Handling a repeat must not duplicate the work.
    • Do not rely on IP allowlisting. Autodesk does not publish an IP address or range for the Webhooks service, because those values are not guaranteed to stay the same. Set a secret token and verify the signature on each callback instead. See How to Verify Payload Signature.
    • Callbacks can arrive late. Most deliveries arrive within seconds or minutes. When a delivery fails, however, retries spread over the following 48 hours, so that notification can reach you long after the event occurred.

    Troubleshooting

    When an event you expected did not arrive, check these in order:

    1. The status of the webhook. Retrieve it by ID. Only a webhook that was active or reactivated at the time the event occurred receives that event.
    2. When the webhook was created. An event published before the webhook existed is not delivered to it.
    3. Whether the event matches the webhook. The event has to match the system, event type, and scope the webhook was created with. If the webhook has a filter, the payload also has to match the filter. See Callback Filtering.
    4. The region. A webhook registered in one region does not receive events published in another. See Regionalization and Data Residency.
    5. Your callback. Confirm it is reachable, returns a 2xx status code within 7 seconds, and is not rejecting the request during signature verification.
    6. Reactivate, then verify. If the webhook is inactive, follow the recovery steps above and confirm the next event arrives.

    If you still need help, have the following ready: the hook ID, the client ID or user ID that registered the webhook, the system and event type it was registered for, and its callback URL.

    Next Steps