To use the Events API, you provide a base URL hosted by a server in your system. Paths are relative to that URL.
As mentioned in the overview, events are grouped into categories, and posted to the webhook for that category:
- Account Events:
/AccountEvent - Authorization Events:
/Authorization - Settlement Events:
/Settlement - Transaction Events:
/Transaction
SoFi Tech Solutions sends event messages receives and expects responses as JSON payloads.
Webhook headers
SoFi Tech Solutions includes the following standard HTTP headers in every webhook POST request across all four event categories.
| Header | Type | Required | Description |
|---|---|---|---|
X-Request-ID | string | Yes | A unique identifier(UUID) for the request, used for tracking and logging. |
Encryption-Type | string | Yes | Signature algorithm. Always "JWT-HS256". |
User-ID | string | Yes | Identifies request as coming from SoFi Tech Solutions. Hard-coded to "galileo". |
Date | string | Yes | UTC timestamp when request is sent. Format: "<timestamp><timezone>" where timestamp = YYYYMMDD:HHMMSS and timezone = UTC. Example: 20170504:141752UTC |
accept | string | No | Generated from available response content types. Allowed: application/json |
Fields
The fields with each event are defined by a template. All available fields listed in the Fields table on every event are automatically included in this template. All fields are sent as strings. For example, $500 is sent as "500.00".
Common fields
All events include the following fields.
| Field | Description |
|---|---|
event_ts | Timestamp for when this event was created in system time. Legacy field: timestamp. Example: "2027-11-22 11:24:02 MST" |
msg_event_id | Unique system-generated identifier for this message. Example: "243693" |
msg_id | The four-letter code to identify this event. Example: "AAAU" |
type | String that identifies the specific event subtype. Example: "auth" |
Empty fields
When there is no data to return for a field, the key is still returned in the response with an empty value. For example, if you receive a BADJ: adj event message for a non-ACH transaction, then "ach_trans_id" is returned in the webhook payload.
Delivery attempts
If a delivery fails, SoFi Tech Solutions resends the event message using the standard exponential backoff. We will retry up to 5 total attempts. After 5 attempts, the event will be marked as undeliverable.
Event handling
When your endpoint receives a webhook, it must validate the request, return a status code, and process the payload according to the following requirements.
Timeouts
You must respond to webhook messages within 5 seconds; otherwise, the request will time out and automatically trigger a retry attempt.
Asynchronous processing
We recommend separating the receipt of the event from your downstream business logic. Return a 200 OK response immediately after validating the webhook request and queuing the event for processing.
Responses
HTTP status codes that your endpoint should return:
| HTTP status code | Description | Scenario |
|---|---|---|
| 200 OK | Successfully received and accepted | Event received, validated, and queued/processed |
| 400 Bad Request | Invalid request format | Malformed JSON or validation errors |
| 422 Unprocessable Content | Logic or validation failure | Incorrect or missing data |
| 401 Unauthorized | Authentication failure | JWT validation failed or invalid token |
| 429 Too Many Requests | Rate limiting triggered | System cannot process more requests at this time |
| 500 Internal Server Error | Server error | Unexpected error while processing |
| 503 Service Unavailable | Service unavailable | Service down for maintenance or experiencing issues |
Map to legacy response codes
Below are the valid legacy status codes for success_code mapped to the HTTP status code:
| Code | Description | HTTP status code |
|---|---|---|
| 0 | Success | 200 |
| 1 | Parameters do not pass validation (parsing error) | 422 |
| 2 | Cardholder account not in system | 422 |
| 3 | General system failure | 500 |
| 4 | Authentication failed | 401 |
| 5 | Not ready to accept messages. Retransmit | 429 |
Note: If you are migrating from the legacy event to the new standard template for the event, keep in mind that returning success_code=3 is now mapped to an HTTP 500 Internal Server Error. For legacy events, 3 was a terminal failure. Now, returning a 500 triggers a retry.
Retry triggers
Retries are automatically triggered if your endpoint times out or returns HTTP status codes (500–599) or rate limiting (429). We do not retry delivery for other HTTP status codes.