Referral Partners: When your customer's link request expires
When you submit POST /clients for an existing Debitura customer and they do not act on the approval link within the configured window, the link request expires and Debitura fires a client.link_expired webhook. This article covers what that means and how to recover.
With the Starter Integration, Debitura emails the approval invitation itself, to the user you submitted with the collection request. The approval expires under the same window (normally 7 days, at most 30). The collection request and its update webhook (collection_request.updated) show the expiry. To start again, send a fresh collection request, which asks for a new approval. Do not replay the original request with the same idempotency key: within 24 hours that returns the original response with the old, expired link. The rest of this article covers the Full Integration (POST /clients).
Problem
You receive a client.link_expired webhook for a customer, or your customer tells you "the link expired" and they cannot approve linking your platform anymore. The customer is still not linked to your platform, and any cases you submitted in the original payload have not landed.
Likely causes
There is only one cause for client.link_expired:
The customer did not open the approval link within the configured approval window. The default window is 7 days; the maximum is 30 days. Your partnership has a specific value configured for it - your developer can confirm what it is set to. Once the window elapses, an hourly background job marks the link request as expired and fires the webhook.
A few related situations look similar but are not the same as client.link_expired:
The customer declined rather than ignored the request. In that case you receive
client.link_declined, notclient.link_expired. Recovery is different - the customer made an active choice not to link, so re-sending the same request is unlikely to succeed.The customer never received the approval link. Debitura does not email the approval link: it creates the pending link request and returns its approval URL, and your platform must deliver that URL (by redirect, an in-app prompt or your own email). If the customer says they never saw it, the issue is delivery, not TTL: check how your platform delivered the URL. If you sent it in your own email, ask the customer to check spam or junk filters.
The customer clicked Approve and got an error. If the customer reports that they tried to approve but saw a "this link has already been used" page, that is the concurrent-click race and not an expiry. The first click usually succeeded - check the customer status before re-sending.
Fix
Recovery is straightforward and does not require Debitura support involvement.
Confirm the webhook event type. Check the event payload to make sure you received
client.link_expiredand notclient.link_declined. The two require different responses.Re-run the same client creation request. Your platform should call
POST /clientsagain with the same external tenant ID and the same payload as the original request. Debitura creates a fresh link request and returns a new approval URL in the response, and (importantly) any cases you included in the original payload are still preserved and will land on approval.Deliver the new approval URL to the customer. Debitura does not email it, so your platform must deliver the newly returned URL itself (by redirect, an in-app prompt or your own email). If you also surface the URL in your own product UI, replace the expired URL there with the new one from the response.
Optionally, ask Debitura to lengthen your approval window. If a meaningful share of your customers are letting their links expire, contact [email protected] to extend your
ApprovalTtlDays. The maximum is 30 days. Chaser is currently configured for 30 days as a reference point.
For the full event reference (including what data each webhook carries), see Referral Partners: Webhook events (business meaning glossary). For the broader 409 path - the full sequence of events from the initial conflict through approval and signing - see Referral Partners: 409 conflict path - what your customer sees and what your platform does.
One timing detail to know about
The expiry check runs hourly, so the client.link_expired webhook can arrive up to one hour after the configured TTL technically passes. If a webhook lands at, for example, day 7 plus 30 minutes for a default-TTL request, that is expected and not a bug.
Escalation
If re-running the client creation request does not produce a fresh approval link, or the new approval link does not work for the customer, contact Debitura support and include:
Your Referral Partner name and Partner ID
The customer's
ExternalTenantIdThe customer's company name and email address
The timestamp on the original 409 response and the timestamp on the
client.link_expiredwebhookWhether the customer has confirmed they did not receive the approval link at all (delivery) or received it and just did not act on it in time (TTL)
Contact: [email protected]. For the full SLA and escalation path, see Referral Partners: Support channels, SLA, and escalation. For broader signup and activation issues beyond expiry, see Referral Partners: Customer signup / activation issues.
What to tell the customer
If your customer has reached out about an expired link, the script in Referral Partners: How to support your customers using Debitura covers what to say. The short version: tell the customer that the original link expired but no data was lost, you will send them a fresh approval link, and they can pick up where they left off as soon as they open it.
Developer Docs: Developers: For the webhook payload schema and signature verification details, see Developer Docs: Referral Partner API.
