Storage & webhooks

Two things the platform keeps for you so a small app needs no database of its own: a per-install key–value store, and webhook delivery for every workspace that installs you. Both are addressed by the install, so an access token is all you need; neither takes a scope.

App data storage

A settings and state store, keyed by install and mode. A zero-backend app keeps its configuration here; an app with a real backend keeps its own data and uses this for the few things that belong with the install.

GET    /v1/app-data              # list this install's keys (values omitted)
GET    /v1/app-data/:key         # one value
PUT    /v1/app-data/:key         # { "value": <any JSON> } — create or replace
DELETE /v1/app-data/:key

await fetch('https://api.paysio.com/v1/app-data/settings', {
  method: 'PUT',
  headers: { Authorization: 'Bearer ' + accessToken, 'Content-Type': 'application/json' },
  body: JSON.stringify({ value: { emailCustomer: true, template: 'default' } }),
})

const res = await fetch('https://api.paysio.com/v1/app-data/settings', {
  headers: { Authorization: 'Bearer ' + accessToken },
})
const { value } = await res.json()   // { emailCustomer: true, template: 'default' }

Webhooks

Set webhooks.url in paysio.app.json and we provision an endpoint for every workspace that installs you, signed with your app’s own webhook secret. You get that secret once, on your app’s page in the dashboard. Deliveries are the same shape, signature and retry policy as a merchant’s own webhooks, with two additions: the platform topics, and scope gating.

Verifying a delivery

import crypto from 'node:crypto'

function verify(rawBody: string, header: string, secret: string): boolean {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')))   // t=..., v1=...
  const expected = crypto.createHmac('sha256', secret).update(parts.t + '.' + rawBody).digest('hex')
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300       // 5 minutes
  return fresh && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1))
}

// Express: app.post('/hooks', express.raw({ type: '*/*' }), (req, res) => { ... })
// Verify the RAW body. A parsed-and-reserialised body will not match.

Platform topics

Always on. An app cannot unsubscribe from being told it was removed or that its permissions changed.

Business topics

A payload is a read: payment.completed carries what GET /transactions/:id would. So each topic is only delivered to apps that declared and were granted its read scope. Declaring a topic without its scope is rejected when you save the config, rather than silently never arriving.

Delivery

• Each delivery carries the workspace it belongs to; one endpoint serves every install.
• Answer 2xx within 10 seconds. Anything else is retried: 8 attempts over about 24 hours with exponential backoff and jitter.
• Deliveries can arrive more than once and out of order. Key your handling on the event id.
• Deliveries stop the moment you are uninstalled or suspended.
• Sandbox events are delivered with mode: "test". Treat them as rehearsals.

The webhook payloads themselves are documented under Webhooks in the core reference; an app receives the same objects a merchant does.