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 email 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.
Problem
You receive a client.link_expired webhook for a customer, or your customer tells you "the email 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 email 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 email. 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 email. If the webhook fired but the customer says they never saw the email, the issue is email deliverability, not TTL. Check spam or junk filters first.
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 generates a fresh approval link, sends a new email to the customer, 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. If your integration relies on email, the customer should receive a new email automatically. If you also surface the URL in your own product UI, refresh that with the new URL 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 customer keeps reporting that no email arrives, 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 email at all (deliverability) 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, your platform will trigger a fresh email, and they can pick up where they left off as soon as it arrives.
Developer Docs: Developers: For the webhook payload schema and signature verification details, see Developer Docs: Referral Partner API.