Receive a Meld webhook event

curl --request POST \
  --url https://api.sumvin.com/v0/webhooks/meld/events \
  --header 'Content-Type: application/json' \
  --data '
{
  "eventType": "<string>",
  "eventId": "<string>",
  "timestamp": "<string>",
  "payload": {
    "paymentTransactionId": "<string>",
    "paymentTransactionStatus": "<string>",
    "transactionType": "<string>",
    "externalCustomerId": "<string>",
    "customerId": "<string>",
    "externalSessionId": "<string>",
    "sessionId": "<string>",
    "serviceProvider": "<string>",
    "paymentMethodType": "<string>",
    "sourceAmount": 123,
    "sourceCurrencyCode": "<string>",
    "destinationAmount": 123,
    "destinationCurrencyCode": "<string>",
    "createdAt": "<string>",
    "updatedAt": "<string>"
  }
}
'

{
  "detail": "No wallet found with ID 12345 for this user.",
  "error_code": "WAL-404-001",
  "instance": "/v0/wallets/12345",
  "status": 404,
  "title": "Wallet Not Found",
  "trace_id": "abc123-def456-ghi789",
  "type": "https://api.sumvin.com/errors/wal-404-001"
}

Webhooks

Receive a Meld webhook event

Receives signed webhook events from Meld for the configured tenant. Used for KYC status changes, ramp transaction lifecycle (TRANSACTION_CRYPTO_PENDING, TRANSACTION_CRYPTO_TRANSFERRING, TRANSACTION_CRYPTO_COMPLETE, TRANSACTION_CRYPTO_FAILED), and bank-linking events. The exact strings appear on the request body’s eventType field.

Signature scheme: Each request carries two headers that must both be present:

meld-signature — base64url-encoded HMAC-SHA256 over the canonical string "{timestamp}.{url}.{body}", signed with the configured Meld webhook secret. The encoding is base64url with padding.
meld-signature-timestamp — unix epoch seconds at which Meld signed the request.

The {url} segment is the full public URL Meld signed against (scheme + host + path + query). Behind a proxy or load balancer, the request’s effective scheme must reflect X-Forwarded-Proto so that verification matches.

Timestamp tolerance: Requests with a timestamp more than 300 seconds (5 minutes) from server time are rejected before HMAC compute, in either direction.

Failure modes: A missing or invalid signature returns 401 with error code MLD-401-001. The detail is a fixed string and never echoes the client-supplied signature or timestamp. Successful delivery returns 200; replays of the same eventId are accepted as 200 no-ops so Meld’s retries are safe. Handler exceptions surface as 5xx so Meld will retry — silent 200-on-error swallowing is no longer permitted.

POST

webhooks

meld

events

Receive a Meld webhook event

curl --request POST \
  --url https://api.sumvin.com/v0/webhooks/meld/events \
  --header 'Content-Type: application/json' \
  --data '
{
  "eventType": "<string>",
  "eventId": "<string>",
  "timestamp": "<string>",
  "payload": {
    "paymentTransactionId": "<string>",
    "paymentTransactionStatus": "<string>",
    "transactionType": "<string>",
    "externalCustomerId": "<string>",
    "customerId": "<string>",
    "externalSessionId": "<string>",
    "sessionId": "<string>",
    "serviceProvider": "<string>",
    "paymentMethodType": "<string>",
    "sourceAmount": 123,
    "sourceCurrencyCode": "<string>",
    "destinationAmount": 123,
    "destinationCurrencyCode": "<string>",
    "createdAt": "<string>",
    "updatedAt": "<string>"
  }
}
'

{
  "detail": "No wallet found with ID 12345 for this user.",
  "error_code": "WAL-404-001",
  "instance": "/v0/wallets/12345",
  "status": 404,
  "title": "Wallet Not Found",
  "trace_id": "abc123-def456-ghi789",
  "type": "https://api.sumvin.com/errors/wal-404-001"
}

Headers

meld-signature

string | null

meld-signature-timestamp

string | null

X-Timestamp-Format

string

Controls how timestamp fields are serialized in JSON response bodies.

Default (header omitted or any other value): epoch milliseconds as integers. iso8601: UTC ISO 8601 strings of the form YYYY-MM-DDTHH:MM:SSZ.

Example: with X-Timestamp-Format: iso8601, the field value 1704067200000 becomes "2024-01-01T00:00:00Z".

Affected fields (recursively, in dicts and arrays): any field whose name ends in _at, plus the literal field names timestamp, period_start, and period_end. All other fields are passed through unchanged.

Only iso8601 is recognized. Any other value (or omitting the header) yields the default epoch-ms representation; the server does not reject unknown values, so this is documented as an example rather than an enum to keep generated clients permissive.

Example:

"iso8601"

Body

application/json

eventType

string

required

Meld event type (e.g. TRANSACTION_CRYPTO_COMPLETE).

eventId

string

required

Unique identifier for the webhook delivery.

timestamp

string

required

Provider-emitted event timestamp.

payload

MeldWebhookEventPayload · object

required

Inner payload of a Meld webhook event for ramp transaction lifecycle.

Captures the documented fields Meld sends in the payload envelope for TRANSACTION_CRYPTO_* events. Marked extra="allow" so future Meld fields are preserved without breaking parsing. Fields are optional except paymentTransactionId, which always identifies the ramp transaction.

Show child attributes

Response

Webhook received

Handle Sumsub Webhook Handle Alchemy Webhook

⌘I