Internal rail inbound callback
curl --request POST \
--url https://spi.sandbox.lerian.net/internal/v1/spi/rail/inbound \
--header 'Content-Type: application/json' \
--data '
{
"payloadHash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
"payloadRef": "<string>",
"receivedAt": "2026-06-14T12:00:00Z",
"source": "<string>",
"channel": "<string>",
"headers": {},
"payload": "<string>"
}
'package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://spi.sandbox.lerian.net/internal/v1/spi/rail/inbound"
payload := strings.NewReader("{\n \"payloadHash\": \"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855\",\n \"payloadRef\": \"<string>\",\n \"receivedAt\": \"2026-06-14T12:00:00Z\",\n \"source\": \"<string>\",\n \"channel\": \"<string>\",\n \"headers\": {},\n \"payload\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
payloadHash: 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855',
payloadRef: '<string>',
receivedAt: '2026-06-14T12:00:00Z',
source: '<string>',
channel: '<string>',
headers: {},
payload: '<string>'
})
};
fetch('https://spi.sandbox.lerian.net/internal/v1/spi/rail/inbound', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://spi.sandbox.lerian.net/internal/v1/spi/rail/inbound"
payload = {
"payloadHash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
"payloadRef": "<string>",
"receivedAt": "2026-06-14T12:00:00Z",
"source": "<string>",
"channel": "<string>",
"headers": {},
"payload": "<string>"
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"processingDecision": "ACCEPTED",
"humanReason": "<string>",
"messageRecordId": "550e8400-e29b-41d4-a716-446655440002",
"quarantineId": "550e8400-e29b-41d4-a716-446655440003"
}{
"correlationId": "req-7a3f9c2e",
"code": "<string>",
"detail": "Property foo is required but is missing.",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
],
"instance": "https://example.com/error-log/abc123",
"status": 400,
"title": "Bad Request",
"type": "https://example.com/errors/example",
"upstream": {
"code": "E4001",
"message": "account not found at provider"
}
}{
"correlationId": "req-7a3f9c2e",
"code": "<string>",
"detail": "Property foo is required but is missing.",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
],
"instance": "https://example.com/error-log/abc123",
"status": 400,
"title": "Bad Request",
"type": "https://example.com/errors/example",
"upstream": {
"code": "E4001",
"message": "account not found at provider"
}
}{
"correlationId": "req-7a3f9c2e",
"code": "<string>",
"detail": "Property foo is required but is missing.",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
],
"instance": "https://example.com/error-log/abc123",
"status": 400,
"title": "Bad Request",
"type": "https://example.com/errors/example",
"upstream": {
"code": "E4001",
"message": "account not found at provider"
}
}{
"correlationId": "req-7a3f9c2e",
"code": "<string>",
"detail": "Property foo is required but is missing.",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
],
"instance": "https://example.com/error-log/abc123",
"status": 400,
"title": "Bad Request",
"type": "https://example.com/errors/example",
"upstream": {
"code": "E4001",
"message": "account not found at provider"
}
}{
"correlationId": "req-7a3f9c2e",
"code": "<string>",
"detail": "Property foo is required but is missing.",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
],
"instance": "https://example.com/error-log/abc123",
"status": 400,
"title": "Bad Request",
"type": "https://example.com/errors/example",
"upstream": {
"code": "E4001",
"message": "account not found at provider"
}
}{
"correlationId": "req-7a3f9c2e",
"code": "<string>",
"detail": "Property foo is required but is missing.",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
],
"instance": "https://example.com/error-log/abc123",
"status": 400,
"title": "Bad Request",
"type": "https://example.com/errors/example",
"upstream": {
"code": "E4001",
"message": "account not found at provider"
}
}{
"correlationId": "req-7a3f9c2e",
"code": "<string>",
"detail": "Property foo is required but is missing.",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
],
"instance": "https://example.com/error-log/abc123",
"status": 400,
"title": "Bad Request",
"type": "https://example.com/errors/example",
"upstream": {
"code": "E4001",
"message": "account not found at provider"
}
}Internal rail inbound callback
Internal-only inbound rail callback guarded by the X-Internal-Callback shared secret. Not a client API surface.
POST
/
internal
/
v1
/
spi
/
rail
/
inbound
Internal rail inbound callback
curl --request POST \
--url https://spi.sandbox.lerian.net/internal/v1/spi/rail/inbound \
--header 'Content-Type: application/json' \
--data '
{
"payloadHash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
"payloadRef": "<string>",
"receivedAt": "2026-06-14T12:00:00Z",
"source": "<string>",
"channel": "<string>",
"headers": {},
"payload": "<string>"
}
'package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://spi.sandbox.lerian.net/internal/v1/spi/rail/inbound"
payload := strings.NewReader("{\n \"payloadHash\": \"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855\",\n \"payloadRef\": \"<string>\",\n \"receivedAt\": \"2026-06-14T12:00:00Z\",\n \"source\": \"<string>\",\n \"channel\": \"<string>\",\n \"headers\": {},\n \"payload\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
payloadHash: 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855',
payloadRef: '<string>',
receivedAt: '2026-06-14T12:00:00Z',
source: '<string>',
channel: '<string>',
headers: {},
payload: '<string>'
})
};
fetch('https://spi.sandbox.lerian.net/internal/v1/spi/rail/inbound', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://spi.sandbox.lerian.net/internal/v1/spi/rail/inbound"
payload = {
"payloadHash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
"payloadRef": "<string>",
"receivedAt": "2026-06-14T12:00:00Z",
"source": "<string>",
"channel": "<string>",
"headers": {},
"payload": "<string>"
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"processingDecision": "ACCEPTED",
"humanReason": "<string>",
"messageRecordId": "550e8400-e29b-41d4-a716-446655440002",
"quarantineId": "550e8400-e29b-41d4-a716-446655440003"
}{
"correlationId": "req-7a3f9c2e",
"code": "<string>",
"detail": "Property foo is required but is missing.",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
],
"instance": "https://example.com/error-log/abc123",
"status": 400,
"title": "Bad Request",
"type": "https://example.com/errors/example",
"upstream": {
"code": "E4001",
"message": "account not found at provider"
}
}{
"correlationId": "req-7a3f9c2e",
"code": "<string>",
"detail": "Property foo is required but is missing.",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
],
"instance": "https://example.com/error-log/abc123",
"status": 400,
"title": "Bad Request",
"type": "https://example.com/errors/example",
"upstream": {
"code": "E4001",
"message": "account not found at provider"
}
}{
"correlationId": "req-7a3f9c2e",
"code": "<string>",
"detail": "Property foo is required but is missing.",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
],
"instance": "https://example.com/error-log/abc123",
"status": 400,
"title": "Bad Request",
"type": "https://example.com/errors/example",
"upstream": {
"code": "E4001",
"message": "account not found at provider"
}
}{
"correlationId": "req-7a3f9c2e",
"code": "<string>",
"detail": "Property foo is required but is missing.",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
],
"instance": "https://example.com/error-log/abc123",
"status": 400,
"title": "Bad Request",
"type": "https://example.com/errors/example",
"upstream": {
"code": "E4001",
"message": "account not found at provider"
}
}{
"correlationId": "req-7a3f9c2e",
"code": "<string>",
"detail": "Property foo is required but is missing.",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
],
"instance": "https://example.com/error-log/abc123",
"status": 400,
"title": "Bad Request",
"type": "https://example.com/errors/example",
"upstream": {
"code": "E4001",
"message": "account not found at provider"
}
}{
"correlationId": "req-7a3f9c2e",
"code": "<string>",
"detail": "Property foo is required but is missing.",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
],
"instance": "https://example.com/error-log/abc123",
"status": 400,
"title": "Bad Request",
"type": "https://example.com/errors/example",
"upstream": {
"code": "E4001",
"message": "account not found at provider"
}
}{
"correlationId": "req-7a3f9c2e",
"code": "<string>",
"detail": "Property foo is required but is missing.",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
],
"instance": "https://example.com/error-log/abc123",
"status": 400,
"title": "Bad Request",
"type": "https://example.com/errors/example",
"upstream": {
"code": "E4001",
"message": "account not found at provider"
}
}Headers
Internal callback shared secret
Body
application/json
SHA-256 hex digest of the referenced payload bytes: 64 hexadecimal characters, either case. Checked against the staged bytes by the handler, which answers 400 on a mismatch for the same ack-table reason as receivedAt.
Example:
"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
Opaque reference to the payload bytes held in the server-side resolver
Timestamp the mesh received the rail message, RFC3339 UTC. Shape is enforced by the handler rather than the schema so an unparseable value is redelivered (400) instead of acknowledged and dropped (422).
Example:
"2026-06-14T12:00:00Z"
Originating rail/source identifier of the inbound message. Lerian's own mesh vocabulary, not a BACEN code.
Optional channel discriminator routing the message to a handler
Forwarded transport headers (e.g. X-Idempotency), used for idempotency and routing
Show child attributes
Show child attributes
Optional base64-encoded payload bytes; staged server-side after hash verification
Response
OK
Outcome of processing the inbound message (e.g. ACCEPTED, QUARANTINED)
Example:
"ACCEPTED"
Safe-to-return human-readable explanation of the decision
UUID of the persisted message record when the message was accepted
Example:
"550e8400-e29b-41d4-a716-446655440002"
UUID of the quarantine record when the message was quarantined
Example:
"550e8400-e29b-41d4-a716-446655440003"
Was this page helpful?