Providing Employer Risk Metrics

Salsa runs a robust credit risk and fraud model that can be enriched with metrics from your platform. When you send Risk Insight Metrics inputs, Salsa improves its ability to detect potential fraud and credit risk.

When should you send the risk metrics?

Our partners can send this information proactively at any time during the employer onboarding. Still, it's also expected that they do so as soon as a new Employer.awaitingRiskInsights event webhook is received. This enables Salsa to maintain up-to-date employer risk metrics as needed for risk analysis.

The flow can be summarized as follows:

sequenceDiagram
		participant W as Salsa Webhook
		actor P as Partner
		participant API as Salsa Rest API
		W->>P: POST {your_webhook}<br>{"data": { "type": "Employer.awaitingRiskInsights", ...}}
		P->>W: 200 OK
		Note over P,P: Salsa requested Risk Insights information trough webhook<br>Partner sends it using Salsa API
		P->>API: POST /api/rest/v1/paystream/risk-insight-inputs
		API->>P: 201 CREATED

Risk Insights Webhook

Listen for events where data.type equals Employer.awaitingRiskInsights.

Sample webhook payload (truncated):

{
  "data": {
    "type" : "Employer.awaitingRiskInsights",
    "attributes": {
      "category": "NOTIFICATION",
      "employerId": "er_309…",
      "employerExternalId": "your_employer_id",
      "externalId": "your_employer_id"
    }
  }
}

Attributes Reference (ref)

• category: The category of the webhook event. Indicates whether the event is a notification or a payroll lifecycle side-effect (LIFECYCLE, NOTIFICATION)
• employerId: The unique identifier for the Employer.
• employerExternalId and externalId: The Id used to represent the object in your system that is mapped to this Employer.

Delivery & security

• Retries: If your endpoint is temporarily unavailable or returns ≥ 400, Salsa will retry deliveries (exponential backoff) (ref)
• Verification: Validate the request signature/header per Salsa’s webhook signing docs. (ref)

How to send Salsa the risk metrics?

When you receive the webhook, please POST the metrics your platform knows about. Full reference: https://docs.salsa.dev/reference/employerriskmetricsonpartnerplatformcreate

Endpoint:

POST https://api.sandbox.salsa.dev/api/rest/v1/paystream/risk-insight-inputs
Content-Type: application/json
Authorization: Bearer <partner_api_token>

Use the sandbox base URL shown above for testing purposes.

Request body (array supports single or batched upserts)

{
  "data": [
    {
      "type": "PaystreamEmployerRiskMetricsOnPartnerPlatformUpsertInput",
      "employerId": "er_309…",
      "revenueInfo": {
        "averageMonthlyRevenue": "1000.00"
      },
      "payingUserInfo": {
        "totalPaymentsCount": 1,
        "subscriptionStatus": "PAYING_USER"
      },
      "riskAssessment": {
        "riskClassification": "LOW_RISK"
      },
      "signUpDate": "2025-08-01",
      "activeFeatures": [
        {
          "name": "PAYMENT_PROCESSING",
          "activeSince": "2025-09-01",
          "paymentsProcessedAmount": "500.00"
        },
        {
          "name": "SCHEDULING",
          "activeSince": "2025-10-01",
          "lastSchedulingDate": "2025-10-05"
        }
      ],
      "acquisitionChannel": "REFERRAL",
      "businessWebsite": "https://docs.salsa.dev"
    }
  ]
}

📘

Field Reference

For a detailed description of all request payload field, check out the Deep Dive - Risk Insights Input Fields page.

Response

201 Created

{
  "data": [
    {
      "id": "erriskmetrics_f49…",
      "employerId": "er_309…"
    }
  ]
}