relayaa / relaya-php

v0.5.0 2026-09-29 14:50 UTC

Requires

• php: >=8.1
• ext-curl: *
• ext-json: *

Requires (Dev)

• phpunit/phpunit: ^10.5

MIT

• signature
• laravel
• hmac
• webhooks
• relaya

Published on Packagist.org on 2026-09-29 15:24 UTC

README

Official SDKs for Relaya. Each one does the same jobs, with the same names where the language allows:

1. Receive: verify the Relaya-Signature on requests Relaya forwards to your endpoint, and read the delivery's details (idempotency key, event ID, attempt, replay ID, original body).
2. Call the API: events (with paging), deliveries and retry, incidents and replay, contracts, destinations, webhooks, projects, alerts.
3. Send webhooks to your customers (all five): outbound.send(...) for every event, one app per customer, their endpoints, and a hosted portal link. Relaya signs with Standard Webhooks, retries and logs.
4. Your users' accounts (all five): connect Zoho, HubSpot, Google, Jira or Shiprocket, call their APIs through the proxy, and sync changes into events.

The CLI (cli) forwards the events Relaya receives to your own computer while you build, and sends signed test events: relaya listen --forward-to http://localhost:3000/webhooks, relaya trigger payment.captured. Download it from the latest release, or go install github.com/relayaa/relaya-sdks/cli/cmd/relaya@latest.

Language	Folder	Install	Receive helpers
Node.js / TypeScript	node	npm install relaya-node	Express middleware, Fetch handler (Next.js, Hono, Bun, Deno, Workers)
Python	python	pip install relaya	Django, Flask, FastAPI
PHP	php	composer require relayaa/relaya-php	Laravel middleware, plain PHP
Go	go	go get github.com/relayaa/relaya-sdks/go	net/http middleware
Java / Kotlin	java	Maven io.github.relayaa:relaya-java	Spring Boot, Servlet

The signature, for any other language

Relaya-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256(secret, "<t>.<raw body>")>

Recompute the HMAC over the exact bytes received, compare in constant time, and reject timestamps more than 5 minutes from now. Dedupe on Idempotency-Key, which stays the same across retries and replays.

Development

SDK	Unit tests
Node	cd node && npm ci && npm test
Python	cd python && PYTHONPATH=src python -m unittest discover -s tests
PHP	composer install && vendor/bin/phpunit (from the repo root)
Go	cd go && go test ./...
Java	cd java && mvn test

Every SDK also has an integration test that runs against a real Relaya (API, ingest and worker) started with APP_ENV=dev and CONTRACT_MIN_SAMPLES=3. Set RELAYA_IT_API_URL (e.g. http://127.0.0.1:18080) and run the same commands.

Test runs on every push, on the oldest and newest supported runtime of each language.

Releasing

Publish a GitHub release with a tag like v0.2.0. Release stamps that version into every SDK, runs the tests again and publishes:

Registry	One-time setup	Then
npm	Create an npm account and the @relaya org. Add a granular access token (publish rights) as the repo secret NPM_TOKEN.	Automatic
PyPI	Create a PyPI account. Under Publishing, add a pending trusted publisher: this repo, workflow release.yml, environment pypi. Set the repo variable PUBLISH_PYPI to true.	Automatic, no token stored
Packagist	Create a Packagist account, Submit this repo's URL, and connect GitHub so it updates on each tag.	Automatic
Go	Nothing. The workflow pushes the go/vX.Y.Z tag Go needs.	Automatic
Maven Central	Verify the io.github.relayaa namespace at central.sonatype.com (sign in with GitHub). Add MAVEN_CENTRAL_USERNAME / MAVEN_CENTRAL_PASSWORD (a user token) and MAVEN_GPG_PRIVATE_KEY / MAVEN_GPG_PASSPHRASE (a GPG key published to keyserver.ubuntu.com).	Automatic

A registry that isn't set up yet is skipped with a note in the run, so they can be switched on one at a time. Secrets go in GitHub → Settings → Secrets and variables → Actions; never in code or chat.

Published names: relaya-node (npm), relayaa/relaya-php (Packagist), relaya (PyPI), github.com/relayaa/relaya-sdks/go (Go) and io.github.relayaa:relaya-java (Maven Central). A published name can't be taken back.

License

MIT