HTTPS¶

• API: All production traffic is TLS-terminated at the edge. Use https://dev-api.withsema.com only; do not use http:// for production.
• Webhooks: Your webhook endpoint must be HTTPS in production so the payload is not sent in the clear. For local development you can use a tunnel (e.g. ngrok).

The official SDKs enforce this: they reject live API keys (sk_live_...) when the base URL is non-HTTPS and not loopback, and warn for other HTTP base URLs.

API keys¶

• Create and manage keys in the dashboard under API keys. Use sk_test_... for development and sk_live_... for production.
• Do not commit keys. Use environment variables (e.g. SEMA_API_KEY) or a secrets manager. Rotate keys if they may have been exposed.
• Send the key as Authorization: Bearer <key> or X-API-Key: <key>.

Webhook signing¶

Webhooks are signed with the Standard Webhooks scheme. Use the webhook secret returned when you create or update an inbox (e.g. whsec_...). Verify every request with the webhook-id, webhook-timestamp, and webhook-signature headers so you only process authentic deliveries. The Python and Node.js SDKs provide a verifier.

Keep the webhook secret confidential. If it is compromised, update the inbox with a new secret so future deliveries use the new key.

Planned¶

• SSRF/egress filtering for outbound webhook requests.
• Secret rotation workflows for webhook secrets and API keys.