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.

Subscribing to Webhooks

To subscribe to a webhook, make sure you have signed up for an account on https://developer.spinwheel.io then head over to https://developer.spinwheel.io/admin. You should be greeted with a table similar to the following:

Go ahead and click "Add Webhook" then fill out the details required including the event name, the URL you want it to POST to and any headers that you would like.

That's it - once you press "Save" we will start sending webhooks to your configured endpoint.

🚧
Production Webhooks
Note - to enable production webhooks, please contact the Spinwheel representative you have been working with

Available Webhooks

The current webhooks that can be subscribed to are as follows:

Webhook Type	Summary
User Payment Status	This webhook emits updates regarding payment status changes for user transactions.
User Connection Status	This webhook emits updates regarding a user's connection status on Spinwheel's platform with liabilities like student loans, credit cards etc. are received though this webhook.
Payment to Platform	This webhook is triggered when the payment request created by a payment to platform changes its state.
Empty Loan Account	This webhook emits notifications regarding student loan accounts that might have been migrated to a different loan servicer.
User Account Disconnect	This webhook is triggered when any account is disconnected for a user.
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)
User Liability Account Transition	This webhook is triggered when a user's student loan account has been transitioned from an in-repayment status to either migrated to a different servicer or paid off.
User Liability Account Refresh	This webhook is triggered when a user's student loan account has successfully been refreshed and is represented by studentLoanAccounts.dataSyncStatus.statusCode: 2000

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

Payloads

Here are the expected payloads for each type of webhook:

UserPaymentStatusWebhook

{
  "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": "66e0e852-83cf-47c3-a7dc-1a000bc83505"
}

UserConnectionStatusWebhook

{
  "userId": "4a8235be-3d6c-42cf-9add-5c8c648d411d",
  "isValid": false,
  "statusCode": 2000,
  "description": "Auth successful",
  "eventType": "USER_CONNECTION_STATUS",
  "liabilityType": "STUDENT_LOAN",
  "webhookId": "66e0e852-83cf-47c3-a7dc-1a000bc83505"
}

PlatformPaymentStatusWebhook

{
  "employerPayerId": "e1b0d89d-6d86-4ff6-a2ab-46b99e2c1b1e",
  "payerId": "c5377424-8122-4dc7-826c-5092197cb78a",
  "requestId": "db21f285-42b5-4382-b177-42d027acb6e3",
  "transactionRequestId": "db21f285-42b5-4382-b177-42d027acb6e3",
  "status": "SCHEDULED",
  "statusComment": "Scheduled payment towards platform",
  "eventType": "PAYMENT_TO_PLATFORM",
  "webhookId": "4a8235be-3d6c-42cf-9add-5c8c648d411d",
  "tag": "Webhook"
}

EmptyLoanAccountWebhook

{
  "userId": "e1b0d89d-6d86-4ff6-a2ab-46b99e2c1b1e",
  "accountId": "11b0d89d-6d86-4ff6-a2ab-46b99e2c1b1e",
  "servicerId": "91b0d89d-6d86-4ff6-a2ab-46b99e2c1b1e",
  "description": "Webhook",
  "eventType": "EMPTY_LOAN_ACCOUNT_WEBHOOK",
  "webhookId": "655eb5c5-76d0-4baf-a455-16f2ccfae8e5"
}

UserAccountDisconnectWebhook

{
  "userId": "11b0d89d-6d86-4ff6-a2ab-46b99e2c1b1e",
  "eventType": "USER_ACCOUNT_DISCONNECT",
  "webhookId": "7ab813cf-12bf-4bd5-b65f-66ffb7be6917",
  "disconnectedAccounts": [
    {
      "accountId": "11b0d89d-6d86-4ff6-a2ab-46b99e2c1b1e",
      "servicerId": "097ac8fa-6b11-49c6-8889-6dec25f83f55",
      "servicerName": "FedLoan Servicing",
      "liabilityType": "STUDENT_LOAN"
    }
  ]
}

UserRefinanceStatusWebhook

{
  "userId": "e1b0d89d-6d86-4ff6-a2ab-46b99e2c1b1e",
  "externalUserId": "e1b0d89d-6d86-4ff6-a2ab-46b99e2c1b1e",
  "applicationId": "e1b0d89d-6d86-4ff6-a2ab-46b99e2c1b1e",
  "status": "PROCESSING",
  "webhookId": "66e0e852-83cf-47c3-a7dc-1a000bc83505",
  "occurredOn": 1645245893901,
  "details": {}
}

UserLiabilityAccountTransition

{
"eventType": "USER_LIABILITY_ACCOUNT_TRANSITION",
"userId": "039f9d90-289b-4481-bd28-8fca52ffd2d4",
"transitionType": "PAID_OFF",
"servicerId": "2e8f52ce-d950-4410-aab1-d02698ccf46b",
"accountId": "270974de-ba17-43c9-993c-66ce525e57c1",  
"previousOutstandingBalance": 0,
"lastPaymentAmount": 53621.71,
"liabilityType": "STUDENT_LOAN",
"webhookId": "1669434136600-0"
}

UserLiabilityAccountRefresh

{
"eventType": "USER_LIABILITY_ACCOUNT_REFRESH",
"userId": "039f9d90-289b-4481-bd28-8fca52ffd2d4",
"servicerId": "2e8f52ce-d950-4410-aab1-d02698ccf46b",
"accountId": "270974de-ba17-43c9-993c-66ce525e57c1",  
"liabilityType": "STUDENT_LOAN",
"webhookId": "1669434136600-0"
}

To learn more about our debt APIs and 1-click solutions, visit spinwheel.io.