How to receive results reliably with Myaza Trust
Receive Myaza results reliably with a signed webhook receiver. Verify the exact bytes, store each event durably and recover retries without repeating the customer action.
Charles Archibong, Co-founder
· 3 min read
Key takeaways
- Tampered and expired signatures are rejected.
- A logical resend triggers one business action.
- Receiver recovery survives a process restart.
- Delayed events cannot overwrite newer state.
- Rotation works through the full grace period.
Receive Myaza results reliably with a signed webhook receiver. Verify the exact bytes, store each event durably and recover retries without repeating the customer action.
Before you begin
A server endpoint that verifies signatures
Durable duplicate handling and retry recovery
An authorised API key for server result retrieval
Use a team member with permission for this control. Check the organisation and environment before changing a setting. Review the current price before a paid check or ongoing enrolment. Screenshots show an example workspace or the public integration reference; they do not show a real customer or a completed paid check.
Set up and use the capability
Step 1: Prepare the backend receiver
Create a public HTTPS endpoint with a valid certificate and no redirect. It must receive the exact raw request body before JSON middleware changes it. Plan a durable inbox keyed by logical event ID and background processing for slow work. The receiver belongs on your backend; a browser callback is not a substitute for reliable result delivery.
Integration reference: Verification algorithm
Step 2: Create the environment’s webhook endpoint
In Sandbox, open Developers → Webhooks → Add endpoint. Enter the Endpoint URL, choose the supported body version and select the event families your integration handles. Select Create endpoint and save the displayed endpoint signing secret in your backend secret store. Keep it separate from your API key. Sandbox and Production need environment-appropriate endpoints and secrets.
Integration reference: Recommended test sequence
Step 3: Verify the V2 signature before parsing
Read X-Myaza-Signature-V2, parse the signed timestamp and v1 candidates, reject invalid or expired timestamps and verify HMAC-SHA256 over timestamp, a full stop and the exact raw bytes. Use the endpoint secret and constant-time comparison. During rotation accept a valid signature from the active or unexpired grace secret. Use the documented SDK or receiver example rather than a made-up signing format.
Integration reference: Signed headers
Step 4: Persist the logical event before acknowledgement
After signature verification, parse the JSON and store its envelope id under a durable unique constraint. Deduplicate business work using that id, not deliveryId. A resend or compatibility alias can carry the same logical event under another delivery. Return 2xx only after durable acceptance; queue slow work separately. A fast 2xx with no durable record can lose the result after a crash.
Integration reference: Idempotency assertion
Step 5: Reconcile the current product result
Use the documented customer, verification, transaction or activity reference for the event family. Keep status and checkStatus distinct for verifications. Events can arrive out of order, so retrieve current resource state or use its supported version before a sensitive change. Unknown optional fields and event types should not crash your receiver. A notification alone is not permission to release funds.
Integration reference: Ordering assertion
Step 6: Test delivery, replay and rotation
Open the endpoint’s Testing action and send a supported simulated event. Inspect delivery history and your receiver’s durable record. Resend it and prove the business action occurs once. Test a non-2xx response, recovery after timeout, a tampered body and an expired signature. Rotate using the grace period and test both signatures before retiring the older receiver secret.
Integration reference: Recommended test sequence
Get more from the capability
Subscribe to the canonical event families needed by your product rather than every catalogue entry without a handler.
Alert your team on repeated failed or dead-lettered deliveries and keep a reconciliation path to the current resource.
Store the exact decision references and explanation with your own action so support can prove what the application did.
Test before relying on it
Run the supported Sandbox or simulator scenarios for this product. Where a tool is Production only, check access and scope first, then use only a permitted, deliberately reviewed Production test. A documentation screenshot or a successful page load is not an end-to-end integration test.
Tampered and expired signatures are rejected.
A logical resend triggers one business action.
Receiver recovery survives a process restart.
Delayed events cannot overwrite newer state.
Rotation works through the full grace period.
Troubleshooting
Signatures fail after parsing JSON
Verify raw bytes before parsing. Re-serialised JSON changes the signed input.
A resend acted twice
Use the logical event id as the durable unique key instead of deliveryId.
Delivery shows success but the account did not change
Inspect queued business processing and correlation. HTTP delivery is not proof of the downstream side effect.
Open the setup and integration references
Read the integration reference
Back to Solutions. Choose the capability you want to activate, then follow its own guide.
Sources
Charles Archibong
Co-founder
Charles Archibong co-founded Myaza Trust. He writes about identity verification, financial technology, and the practical work of building trusted digital services.
