Troubleshooting

A setting the feature needs is empty. The message names it:

The package doesn't load its migration automatically; it has to be published and run. Or you changed oauth.table after migrating.

The Integration Key is wrong, truncated, revoked, or belongs to a different environment. A stray quote or space in .env is common.

The callback couldn't match the state in the URL with the one stored in the session. The package pulls the state on first use, so it fails when:

• the session expired or was regenerated while the user was at Adobe;
• the session cookie wasn't sent on the redirect back (a SameSite=strict cookie, or the callback is on a different domain or scheme than the redirect route);
• the user started twice in two tabs and finished the older one;
• the callback URL was reloaded or replayed, which is the protection working.

A 400 also happens when the URL has no code, or the api_access_point isn't an Adobe host.

The redirect URI your app sends doesn't match one registered on the Adobe application character for character. Behind a proxy, route('adobe-sign.oauth.callback') may come out as http:// or with an internal host.

NO_TOKEN: the user never connected (or the key differs, e.g. after changing resolveUserKeyUsing()). The others: the refresh token went unused for 60 days, or the user or an admin revoked access.

Tokens are encrypted with APP_KEY, and it changed, or differs between servers.

Adobe verifies the URL immediately with a GET and expects a 2xx with the client-id echo. It fails when the URL isn't publicly reachable over HTTPS, when the client id Adobe sends isn't allowed (your route answers 403), when middleware intercepts the request, or when the allow-list isn't configured at all (500).

route('adobe-sign.webhook') produced an http:// URL: APP_URL is http, or a TLS-terminating proxy isn't trusted, or the code runs in a queue or console where only APP_URL is known.

The X-AdobeSign-ClientId header is missing or not in ADOBE_SIGN_WEBHOOK_CLIENT_IDS (or ADOBE_SIGN_CLIENT_ID when that list is empty). Typical after adding a second Adobe application, or when webhooks are created with an Integration Key and the allow-list holds an OAuth app's id.

Session, CSRF or auth middleware is running on the route: web or auth was added to webhooks.middleware, or a global middleware applies to every route.

Most often your listeners are queued and no worker is processing that queue. Other causes: the listener isn't registered (discovery off, or the event cache is stale), the delivery was a duplicate and correctly ignored, the listener returns early because the event isn't the type it expects, or the job failed.

Dedupe keys live in the cache. With a per-server store (file, array, APCu) a retry landing on another server isn't recognised, and php artisan cache:clear forgets every key. A queued job can also run twice after a timeout, and two different notifications can lead to the same action.

The default cache store is local to each machine (for example file), so neither the data-centre lookup nor the webhook ids are shared.

Adobe disables a webhook after 72 hours of failed deliveries (an outage, an expired certificate, a broken deploy, a 403 after an allow-list change). Notifications while it is disabled are not sent later.

The request went to the wrong data centre. The SDK already handles the normal case: on this error it forgets the cached data centre, rediscovers it and retries once. If you still see it, the rediscovery itself points somewhere the credentials don't belong: a wrong bootstrap_url (for example a Gov Cloud account against the commercial host), or an OAuth token whose stored api_access_point no longer matches the account.

The request is valid, but the Acrobat Sign account's plan or settings don't allow it: mixed sequential and parallel signing (hybrid routing), an identity method that isn't enabled or has no quota, digital signatures not enabled for AES or QES.

Adobe is still processing the document; the status is DOCUMENTS_NOT_YET_PROCESSED for a few seconds.

Adobe throttled the account and asked for a wait longer than retries.max_delay_seconds, or retries ran out.

The whole request took more than 5 seconds, usually because a listener isn't queued, or QUEUE_CONNECTION=sync in production.

Long-running processes loaded config at start. The manager itself is rebuilt per request and per job, but from the config the process already has.