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.

EnvironmentIPs
Sandbox34.203.72.127
52.2.114.95
52.12.60.65
Production44.232.30.137
3.230.55.249

Subscribing to Webhooks

Subscribe by API

As the preferred method for webhook management, you may head on over to our Webhook APIs to Create, Edit, Retrieve and Delete

📘

Head on over to the APIs above and get started!

Or click here!

Subscribe by Developer Portal

Additionally, you may subscribe to a webhook via the Developer Portal. 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 TypeSummary
USER_LIABILITIES_CONNECTEDThis webhook emits updates regarding the first connection status of user liabilities.
USER_LIABILITIES_CONNECTION_FAILEDThis webhook emits based on the first connection failure status of a user's liabilities.
USER_CREDIT_PROFILE_TRANSACTIONThis webhook emits based on latest credit report subscription renewal when there is a successful credit report pull.
USER_CREDIT_PROFILE_TRANSACTION_FAILEDThis webhook emits based on latest credit report subscription renewal when there is a failure to pull the credit report.
REFRESH_TRANSACTION_STATUSThis 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.
USER_PAYMENT STATUSThis webhook emits updates regarding payment status changes for user transactions.
PLATFORM_PAYMENT_STATUSThis webhook is triggered when the payment request created by a payment to platform changes its state.
USER_REFINANCE_STATUSThis webhook is triggered when a refinance application status change is received for a user. (Note, it currently only supports a change to CONVERTED)
USER_ACCOUNT_DISCONNECTThis webhook is triggered when any account is disconnected for a user.
USER_CONNECTION_STATUSThis webhook emits updates regarding a user's student loan connection status on Spinwheel's platform. Note: This will only be fired in response to student loan connection changes.
EMPTY_LOAN_ACCOUNTThis webhook emits notifications regarding student loan accounts that might have been migrated to a different loan servicer.
USER_LIABILITY_ACCOUNT_TRANSITIONThis 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_REFRESHThis webhook is triggered when a user's student loan account has successfully been refreshed and is represented by studentLoanAccounts.dataSyncStatus.statusCode: 2000

Payloads

Here are the expected payloads for each type of webhook:

USER_LIABILITIES_CONNECTED Webhook

{
  "eventType": "USER_LIABILITIES_CONNECTED",
  "userId": "3a35a0ba-9656-4b33-ac4f-2fa6dacae8a6",
  "extUserId":"b1de1852-dc05-443a-8d13-bd81b4fdf006",
  "createdOn":1708637591000,
  "webhookId": "1669434136600-0"
}

USER_LIABILITIES_CONNECTION_FAILED Webhook

{
  "eventType": "USER_LIABILITIES_CONNECTION_FAILED",
  "bureau":"Equifax",
  "userId": "3a35a0ba-9656-4b33-ac4f-2fa6dacae8a6",
  "extUserId":"b1de1852-dc05-443a-8d13-bd81b4fdf006",
  "createdOn":1708637591000,
  "webhookId": "1669434136600-0"
}

USER_CREDIT_PROFILE_TRANSACTION Webhook

{
      "userId": "3a35a0ba-9656-4b33-ac4f-2fa6dacae8a6",
      "extUserId":"b1de1852-dc05-443a-8d13-bd81b4fdf006" ,
      "createdOn":1708637591000,
      "subscriptionId": "28ddf73b-bd93-4c06-afa5-fd4e3994d23f",
      "status":"COMPLETED",//or "PENDING"
      "metadata": {
        "creditReportType": "FULL",
        "creditScoreModel": "EquifaxVantageScore3.0",
      },
      "bureau":"Equifax",
    }

USER_CREDIT_PROFILE_TRANSACTION_FAILED Webhook

{
      "userId": "3a35a0ba-9656-4b33-ac4f-2fa6dacae8a6",
      "extUserId":"b1de1852-dc05-443a-8d13-bd81b4fdf006" ,
      "createdOn":1708637591000,
      "subscriptionId": "28ddf73b-bd93-4c06-afa5-fd4e3994d23f",
      "status":"FROZEN_REPORT",//or "FRAUDULENT_REPORT" or "REPORT_FAILED"
      "metadata": {
        "creditReportType": "FULL",
        "creditScoreModel": "EquifaxVantageScore3.0",
      },
      "bureau":"Equifax",
    }

REFRESH_TRANSACTION_STATUS Webhook

{
  "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

{
  "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",
  "paymentTraceNumber":"123456789",//for APPLIED/FAILED/RETURNED
  "errorDescription":"Invalid account number provided for the account to be paid."// for FAILED/RETURNED
}
1. Launch loan-servicers-login DIM via your sandbox partner
2. Connect with the "Single Step MFA" Servicer available at the bottom of the list
3. Use credentials "testUser" and "testPass" to properly authenticate
4. Add a test bank account in the precision-pay DIM (or reference whatever payer you would like for the paymentRequest with the newly created userId)
5. Make the paymentRequest (and capture the requestId for hitting the process endpoint)
6. Ping the sandbox/payments/process endpoint with the appropriate extRequestId (requestId) or requestId (transactionRequestId)
7. The transaction will process immediately, and move from SCHEDULING -> PROCESSING -> SCHEDULED
8. The webhook will be triggered

PLATFORM_PAYMENT_STATUS Webhook

{
  "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": "4a8235be-3d6c-42cf-9add-5c8c648d411d",
  "tag": "Webhook"
}

USER_REFINANCE_STATUS Webhook

{
  "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": {}
}

USER_ACCOUNT_DISCONNECT Webhook

{
  "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"
    }
  ]
}

USER_LIABILITY_ACCOUNT_TRANSITION Webhook

{
"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"
}

USER_CONNECTION_STATUS Webhook

{
  "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"
}

USER_LIABILITY_ACCOUNT_REFRESH Webhook

{
"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"
}

EMPTY_LOAN_ACCOUNT_WEBHOOK

{
  "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"
}

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