---
updatedAt: 2026-08-12T17:30:28.000Z
agentTools:
projectIndex: https://docs.spinwheel.io/llms.txt
---
# Webhooks
This guide will describe how to integrate with and consume Spinwheel webhooks.
## Overview
Webhooks allow our partners to subscribe to various events that occur within the Spinwheel system. Once subscribed, if an event occurs, we will send a POST request to an endpoint you have configured with information about the event and, optionally, any headers that you have configured.
## Whitelisting IPs
### Important
For each environment where these webhooks are consumed, certain IPs are to be whitelisted. Note the IPs listed per environment in the table below.
| Environment | IPs |
| :---------- | :---------------------------------------------- |
| Sandbox | 34.203.72.127
52.2.114.95
52.12.60.65 |
| Production | 44.232.30.137
3.230.55.249 |
## Subscribing to Webhooks
Head on over to our Webhook APIs to [create](https://docs.spinwheel.io/reference/create-webhook), [edit](https://docs.spinwheel.io/reference/update-webhook), [retrieve](https://docs.spinwheel.io/reference/get-webhooks-list) and [delete](https://docs.spinwheel.io/reference/delete-webhook) webhooks.
## Webhook Retries
There is an initial webhook, and if it fails to be received Spinwheel retries those webhooks with an exponential backoff of 5mins, 30mins, and 60mins for a total of 4 potential webhook events.
`webhookIds` are referenced as \[epoch timestamp]-\[# of retries], so an example pulled from the below mocked payloads: `"webhookId": "1773694304981-0"`.
## Available Webhooks
The current webhooks that can be subscribed to are as follows:
| Webhook Type | Summary | Related Products |
| :---------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------- |
| SUBSCRIPTION\_ACTIVATED | This webhook is triggered when a user is successfully enrolled in a Debt Profile Refresh Subscription. | Debt Profile Refresh Subscription |
| SUBSCRIPTION\_FAILED | This webhook is triggered when a user fails to be enrolled in a Debt Profile Refresh Subscription. | Debt Profile Refresh Subscription |
| USER\_CREDIT\_PROFILE\_TRANSACTION | This webhook is triggered based on latest Debt Profile Refresh Subscription renewal when there is a successful credit report pull. | Debt Profile Refresh Subscription |
| USER\_CREDIT\_PROFILE\_TRANSACTION\_FAILED | This webhook is triggered based on latest Debt Profile Refresh Subscription renewal when there is a failure to pull the credit report. | Debt Profile Refresh Subscription |
| REFRESH\_TRANSACTION\_STATUS | This webhook is triggered when a refresh liability status changes to either COMPLETED or FAILED. **Please note this is specifically for the refresh liability functionality, not refresh user**. | Real-TIme Liability Data |
| USER\_PAYMENT\_STATUS | This webhook emits updates regarding payment status changes for user transactions. | Payments |
| PLATFORM\_PAYMENT\_STATUS | This webhook is triggered when the payment request created by a Payment to Platform changes its state. | Payments |
| USER\_REFINANCE\_STATUS | This webhook is triggered when a refinance application status change is received for a user. (Note, it currently only supports a change to CONVERTED) | Refinance |
| BANK\_ACCOUNT\_LOOKUP\_STATUS\_CHANGE | This webhook is triggered when the status of a bank account information lookup transaction changes to either COMPLETED or FAILED | Bank Account |
| LIABILITY\_GROUP\_PAYOFF\_QUOTE\_STATUS\_CHANGE | This webhook is triggered when the status of a student loan payoff quote lookup transaction changes to either COMPLETED or FAILED | Student Loan |
## Payloads
Here are the expected payloads for each type of webhook:
### SUBSCRIPTION\_ACTIVATED Webhook
```json
{
"eventType": "SUBSCRIPTION_ACTIVATED",
"userId": "3a35a0ba-9656-4b33-ac4f-2fa6dacae8a6",
"extUserId": "b1de1852-dc05-443a-8d13-bd81b4fdf006",
"subscriptionId": "28ddf73b-bd93-4c06-afa5-fd4e3994d23f",
"status": "COMPLETED", //status will always be COMPLETED for a success
"createdOn": 1708637591000,
"metadata": {
"creditReportType": "FULL",
"creditScoreModel": "EquifaxVantageScore3.0"
},
"bureau": "Equifax",
"webhookId": "1773694304981-0"
}
```
### SUBSCRIPTION\_FAILED Webhook
```json
{
"eventType": "SUBSCRIPTION_FAILED",
"userId": "3a35a0ba-9656-4b33-ac4f-2fa6dacae8a6",
"extUserId": "b1de1852-dc05-443a-8d13-bd81b4fdf006",
"subscriptionId": "28ddf73b-bd93-4c06-afa5-fd4e3994d23f",
"status": "REQUEST_FAILED", //status will always be REQUEST_FAILED for a failure
"createdOn": 1708637591000,
"metadata": {
"creditReportType": "FULL",
"creditScoreModel": "EquifaxVantageScore3.0"
},
"bureau": "Equifax",
"webhookId": "1773693912561-0"
}
```
### USER\_CREDIT\_PROFILE\_TRANSACTION Webhook
```json
{
"userId": "3a35a0ba-9656-4b33-ac4f-2fa6dacae8a6",
"extUserId": "b1de1852-dc05-443a-8d13-bd81b4fdf006",
"eventType": "USER_CREDIT_PROFILE_TRANSACTION",
"createdOn": 1708637591000,
"subscriptionId": "28ddf73b-bd93-4c06-afa5-fd4e3994d23f",
"status": "COMPLETED", // Or PENDING
"metadata": {
"creditReportType": "FULL",
"creditScoreModel": "EquifaxVantageScore3.0"
},
"bureau": "Equifax",
"webhookId": "1773694304981-0"
}
```
### USER\_CREDIT\_PROFILE\_TRANSACTION\_FAILED Webhook
```json
{
"userId": "3a35a0ba-9656-4b33-ac4f-2fa6dacae8a6",
"extUserId":"b1de1852-dc05-443a-8d13-bd81b4fdf006",
"eventType":"USER_CREDIT_PROFILE_TRANSACTION_FAILED",
"createdOn":1708637591000,
"subscriptionId": "28ddf73b-bd93-4c06-afa5-fd4e3994d23f",
"status":"FROZEN_REPORT",//or "FRAUDULENT_REPORT" or "REPORT_FAILED"or "CREDIT_REPORT_NOT_FOUND" or "MANUAL_FILE" or "MANUAL_REVIEW_REQUIRED" or "REFERRED_FILE" or "LOCKED_REPORT"
"metadata": {
"creditReportType": "FULL",
"creditScoreModel": "EquifaxVantageScore3.0"
},
"bureau":"Equifax",
"webhookId": "1773694304981-0"
}
```
### REFRESH\_TRANSACTION\_STATUS Webhook
```json
{
"eventType": "REFRESH_TRANSACTION_STATUS",
"userId": "b790770b-33c7-49d4-b086-e6e18864ba34",
"extRequestId": "28ddf73b-bd93-4c06-afa5-fd4e3994d23f",
"refreshTransactionId": "b790770b-33c7-49d4-b086-e6e18864ba34",
"creditCardId": "007035e0-7865-49f3-be50-c922b1c63dc6",
"refreshTransactionStatus": "COMPLETED", // or "FAILED"
"webhookId": "1710361341615-0",
"data": {
"balanceDetails": {
"outstandingBalance": 7000,
"updatedOn": 1597753517524
},
"statementSummary": {
"refreshedFields": {
"lastPaymentDate": {
"value": "2021-08-21",
"format": "YYYY-MM-DD",
"updatedOn": 1643917894780
},
"dueDay": {
"value": "08",
"format": "DD",
"updatedOn": 1643917894780
},
"lastPaymentAmount": {
"value": 400,
"updatedOn": 1643917894780
}
}
}
}
}
```
### USER\_PAYMENT\_STATUS Webhook
```json
{
"userId": "e1b0d89d-6d86-4ff6-a2ab-46b99e2c1b1e",
"status": "SCHEDULED",
"statusComment": "Scheduled payment towards loan account",
"requestId": "a564cbf8-8669-481d-ad4b-82843462b31c",
"transactionRequestId": "c8301530-b77e-46c5-9c03-8d3233ff6b8d",
"transactionId": "f9bcb792-7af5-4eee-a561-3b6bed634556",
"eventType": "USER_PAYMENT_STATUS",
"liabilityType": "STUDENT_LOAN",
"webhookId": "1773694304981-0",
"paymentTraceNumber":"123456789",//for APPLIED/FAILED/RETURNED
"errorDescription":"Invalid account number provided for the account to be paid."// for FAILED/RETURNED
}
```
### PLATFORM\_PAYMENT\_STATUS Webhook
```json
{
"employerPayerId": "e1b0d89d-6d86-4ff6-a2ab-46b99e2c1b1e",//for employment benefits only
"payerId": "c5377424-8122-4dc7-826c-5092197cb78a",//for non-employment benefits
"requestId": "db21f285-42b5-4382-b177-42d027acb6e3",
"transactionRequestId": "db21f285-42b5-4382-b177-42d027acb6e3",
"status": "SCHEDULED",
"statusComment": "Scheduled payment towards platform",
"eventType": "PLATFORM_PAYMENT_STATUS",
"webhookId": "1773694304981-0",
"tag": "Webhook"
}
```
### USER\_REFINANCE\_STATUS Webhook
```json
{
"userId": "e1b0d89d-6d86-4ff6-a2ab-46b99e2c1b1e",
"externalUserId": "e1b0d89d-6d86-4ff6-a2ab-46b99e2c1b1e",
"applicationId": "e1b0d89d-6d86-4ff6-a2ab-46b99e2c1b1e",
"status": "PROCESSING",
"webhookId": "1773694304981-0",
"occurredOn": 1645245893901,
"details": {}
}
```
### BANK\_ACCOUNT\_LOOKUP\_STATUS\_CHANGE Webhook
```json
{
"eventType": "BANK_ACCOUNT_LOOKUP_STATUS_CHANGE",
"webhookId": "1744732334424-0",
"status": "COMPLETED",
"transactionId": "41896b74-1b1c-461e-b311-a1d2202d3854",
"userId": "4f7fb087-d8d8-40a5-a39f-69ead67fcd8b",
"bankAccountId": "464e5005-4397-4abb-b4ec-00ee26600860",
"nextEligibleRefreshOn": 1744732357083,
"data": {
"accountBalance": 1700
}
}
```
### LIABILITY\_GROUP\_PAYOFF\_QUOTE\_STATUS\_CHANGE Webhook
```json
{
"webhookId": "1710361341615-0",
"eventType": "LIABILITY_GROUP_PAYOFF_QUOTE_STATUS_CHANGE",
"liabilityType": "STUDENT_LOAN",
"userId": "b790770b-33c7-49d4-b086-e6e18864ba34",
"extRequestId": "28ddf73b-bd93-4c06-afa5-fd4e3994d23f",
"refreshTransactionId": "3a3d045d-9b34-472a-9878-9d1d6f2f98da",
"liabilityGroupId": "c4188033-8462-41bb-901a-62329dd9bb92",
"refreshTransactionStatus": "COMPLETED | FAILED",
"nextEligibleRefreshOn": 1746053825213,
"studentLoanIds": ["039fc2c9-eacd-4db5-aedb-a85efa276116", "983e7b73-bf7b-4c0d-b849-6cd7c7945f46"],
"data": {
"payoffAmount": 28014,
"payoffGoodThroughDate": "2025-05-30",
"updatedOn": 1745621877124
}
}
```
To learn more about our APIs, visit [spinwheel.io](https://spinwheel.io/).