How it works
- Create an endpoint for an app environment in the Partner Dashboard. Stableyard shows its signing secret once.
- A resource changes, such as a payment succeeding or a deposit settling, and Stableyard records an event.
- Stableyard sends the event as a signed
POSTto every active endpoint in that app environment subscribed to the event name. - Your handler verifies and records it, returns
2xx, then reads the resource for its current state.
An event is a prompt to read
An event says something changed. The resource says what is true now. Events are additive, may be delivered more than once and may arrive out of order, so never reconstruct state from delivery order: fetch the resource, such asGET /v2/payments/{paymentId}, and act on what it returns. See Reconciliation.
New partner events are added over time. Your consumer must ignore an unknown event name safely rather than throw.
Creating an endpoint
Create and manage endpoints in the Partner Dashboard, under Developers → Webhooks. Each endpoint belongs to one app environment.
Stableyard sends partner-facing lifecycle events for every account owned by that app environment. A second endpoint with the same URL in the same app environment is refused.
Managing an endpoint
Each endpoint’s deliveries and their outcomes are under Developers → Event stream. See Delivery and retries. Disabling, archiving or unsubscribing changes what happens to deliveries still waiting. See Delivery and retries.
Delivery guarantees
Delivery is at-least-once, so the same event may arrive again. Dedupe on two levels:- By
x-stableyard-deliveryfor delivery-level retries, which reuse the same delivery attempt. - By
x-stableyard-event-idplus the resource ID in the payload for resource-level processing.
What a delivery contains
Every delivery is aPOST with a JSON body and these headers:
id, name, apiVersion, createdAt and payload. id is the event’s stable ID, the same value as x-stableyard-event-id. Treat it as an opaque string. apiVersion is the immutable date-version of the resource and event contract; use it to select your decoder rather than inferring the version from delivery time. What each payload carries is in the Event catalog.
Events for public wallet Payments carry no account ID, in the payload or the headers.
A minimal handler
- Read the raw request bytes. Do not parse JSON first.
- Verify the signature. See Verifying signatures.
- In one database transaction, record
x-stableyard-event-idunder a unique constraint and apply the event. On a conflict, skip the business effect. - Return
2xxafter the transaction commits. - Read the resource before acting on anything user-visible.
5xx from your handler is retried; a 400 is abandoned at once. Return 5xx when your own database is down, so the event comes back.
Related
Event catalog
Every partner event, what it means and which to subscribe to.
Verifying signatures
Check each delivery’s HMAC-SHA256 signature before you trust it.
Delivery and retries
Retries, backoff, abandonment and requeueing a delivery.
Reconciliation
Why an event is a prompt to read the resource, and what to persist alongside the event ID.