Configure webhook endpoints separately for Sandbox and Production.
Set up webhooks
Configure webhook endpoints in the Truv Dashboard:- Navigate to Development → Webhooks
- Enter your endpoint URL
- Save the configuration
Test webhooks
- Use Truv Bridge in the Dashboard Emulator to trigger webhook events in sandbox
- Use tools like ngrok to expose a local development server:
Webhook payload structure
All webhook requests include these standard fields:Headers
| Header | Value |
|---|---|
User-Agent | Truv-Webhook-Service/2.0 |
X-WEBHOOK-SIGN | HMAC-SHA256 signature for verification |
HTTP header names are case-insensitive per RFC 7230.
Body fields
Every webhook payload includes these common fields:| Field | Description |
|---|---|
webhook_id | Unique identifier for this webhook request |
event_type | The event classification |
event_created_at | Timestamp when the event occurred |
user_id | Associated Truv user identifier |
Security
Every webhook includes anX-WEBHOOK-SIGN header with an HMAC-SHA256 signature. Verify it against the raw request body using your Access Secret before processing the event.
How it works
- Truv computes an HMAC-SHA256 hash of the raw request body using your Access Secret
- The hash is sent in the
X-WEBHOOK-SIGNheader with av1=prefix - Your server recomputes the hash and compares it to the header value
Code examples
Python
Python
Node.js
Node.js
Go
Go
Ruby
Ruby
C#
C#
Originating IP addresses
Allowlist the current Truv webhook IP addresses if your network requires source filtering:34.212.57.9344.224.243.16652.25.14.79
Additional authentication options
Beyond signature verification, Truv supports:- Truv-signed certificates for webhook mTLS
- Client-signed certificates for webhook mTLS
- OAuth 2.0, where Truv obtains access tokens for secure webhook delivery (optional, configured with Truv)
- Custom headers such as client ID and client secret, configured with Truv
Timeouts and retries
| Behavior | Detail |
|---|---|
| Timeout | Your endpoint must respond with a 2xx status within 10 seconds |
| Redirects | 3xx responses are followed |
| Retries | 4xx and 5xx responses trigger up to 3 retry attempts at 30-second intervals |
| Failed delivery | After the 3 retry attempts fail, Truv stops retrying that event and marks the delivery failed |
Event ordering
Webhooks are delivered in event order. For example,full_parse fires before done. However, network conditions can cause delays in delivery.
Handle webhooks
Best practices
Respond within 10 seconds
Respond within 10 seconds
Return a
200 response quickly. Process the webhook data asynchronously if needed:Handle duplicates with idempotency
Handle duplicates with idempotency
Webhooks may be delivered more than once. Use the
webhook_id field for idempotency:Always verify signatures
Always verify signatures
Never process a webhook without verifying the
X-WEBHOOK-SIGN header. See Security above.Track the task-status-updated event
Track the task-status-updated event
The
task-status-updated event is the primary signal for monitoring connection progress. Key statuses to handle:done: All data has been downloaded and processed. Fetch verification reports.login_error: Authentication failed. The user may need to retry.mfa_error: MFA verification failed.config_error: Provider configuration issue.
Troubleshooting
| Issue | Solution |
|---|---|
| Not receiving webhooks | Verify your URL is configured under Development → Webhooks for the correct environment |
| Signature verification failing | Ensure you’re using your Access Secret (not Client ID) and hashing the raw body |
| Timeouts | Respond with 200 immediately, process asynchronously |
| Failed deliveries | Each event is retried up to 3 times (30s apart), then marked failed. Use the Webhook request history to find and debug failed deliveries |
Events by object
Orders (see more)| Event | Trigger |
|---|---|
order-created | Order first created, before any status transitions |
order-status-updated | Order status changes |
order-refresh-failed | Refresh task fails for an order |
order-finalized | Order group reaches its terminal, final state |
certification-completed | Applicant submits their income self-certification |
| Event | Trigger |
|---|---|
task-status-updated | Task status transitions |
| Event | Trigger |
|---|---|
bank-accounts-created | First bank account discovery |
bank-accounts-updated | Bank accounts changed on refresh |
| Event | Trigger |
|---|---|
shifts-created | First shift extraction |
shifts-updated | Shifts changed on refresh |
| Event | Trigger |
|---|---|
statements-created | First statement retrieval |
statements-updated | New statements on refresh |
| Event | Trigger |
|---|---|
profile-created | First profile extraction |
profile-updated | Profile changed on refresh |
| Event | Trigger |
|---|---|
employment-created | First employment extraction |
employment-updated | Employment changed on refresh |
| Event | Trigger |
|---|---|
link-connected | Successful connection |
link-disconnected | Refresh connection failure |
link-deleted | Data and credentials removed |