API keys and webhooks

Start safely in the sandbox

The sandbox credential works only in /api/sandbox/v1. It sends no email or SMS and creates no charge. Do not use real medical data in the sandbox.

1. 1From Developers, choose Start in sandbox and create a separate sandbox credential.
2. 2Run a synthetic scenario. Changing scenario starts a new operation; retrying the same scenario keeps its reference. The HTTP result, rate limit and reference appear below the form.
3. 3Add your HTTPS webhook subscribed to webhook.test, send a signed test and verify its signature with the secret shown once. In Requests and deliveries, inspect the actual response and permitted retry. Then create a separate scoped credential for the live clinic.

API key

1. 1Choose a descriptive name.
2. 2Select only the permissions needed.
3. 3Set a reasonable expiry, 90 days by default.
4. 4Copy the secret immediately; it cannot be revealed again.
5. 5Send Idempotency-Key when creating a handover, recipient or file request. Repeating the same body returns the original result; a changed body is rejected. File uploading is not idempotent.
6. 6Revoke the key if compromised or when the integration is no longer needed.

Webhook signature

Verify HMAC-SHA256 over timestamp, a dot, MediSend-Delivery, a dot and the raw body. Accept timestamps only within five minutes. Atomically record payload.id to avoid processing one event twice; MediSend-Delivery identifies the particular delivery. Verify the signature before processing. The payload contains no clinical text or arbitrary audit metadata.

Checking an interrupted API upload

After an uncertain multipart upload, check GET /api/v1/handovers/{id} with handovers:read before retrying. data.files contains an identifier, SHA-256, size, scan status and upload time only for integration-uploaded files. Compare size and checksum with the original file. It contains no filenames, clinical content, DICOM details or download URLs. A recorded file is not necessarily clean or part of a sent handover; inspect the draft in MediSend if the match is uncertain.

• API documentation and examples

Secret rotation

For 24 hours after rotation, deliveries include a v1 signature using the new secret and a v0 signature using the old one. Update the receiving system during that period; the old secret is not used afterward.

Errors

MediSend records attempts, HTTP status and a safe error category. Repeated persistent failures automatically disable the endpoint.