Webhooks

SOMA Next POSTs a JSON body to your endpoint when subscribed events occur.

Payload

{
  "event": "simulation.created",
  "data": { "simulation_id": "…", "name": "…" }
}

Verifying the signature

Each request includes an X-Soma-Signature: sha256=<hmac> header — an HMAC-SHA256 of the raw request body using your endpoint's signing secret (shown once when you create the endpoint). Compare it constant-time:

import hmac, hashlib

def verify(secret: str, body: bytes, header: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, header)

Delivery & retries

• Respond 2xx within 10s to acknowledge.
• Non-2xx / timeouts are retried with exponential backoff (up to 6 attempts).
• Use the X-Soma-Event header to route by type.
• Send a Test event from your webhooks settings.