Receive terminal Morface job events, verify signatures, and implement safe retry handling.

Webhooks

Morface webhooks notify your backend when a job reaches a terminal state.

Supported events

job.completed
job.failed
job.cancelled

Intermediate states such as queued or processing are not sent through webhook delivery.

Submit shape

Attach webhook settings to your submit payload:

{
  "webhook": {
    "url": "https://example.com/morface/webhook",
    "secret": "whsec_demo",
    "events": ["job.completed", "job.failed", "job.cancelled"]
  }
}

If events is omitted, Morface subscribes the job to all terminal events.

Request headers

X-Morface-Event-Id
X-Morface-Timestamp
X-Morface-Signature

Signature verification

When you supply a webhook secret, the signature format is:

hex(hmac_sha256(secret, timestamp + "." + rawBody))

Verify the raw request body exactly as delivered before you parse the JSON payload.

Retry behavior

Any 2xx response marks delivery successful.

If the endpoint times out or returns a non-2xx, Morface retries with this schedule:

Immediately
After 1 minute
After 5 minutes
After 30 minutes
After 6 hours

Payload shape

Terminal webhook payloads include:

event_id
event_type
occurred_at
job.uuid
job.status
job.status_detail
job.error_message
job.error_type
job.result_ready

Best practices

Acknowledge quickly and move slow downstream work into your own queue.
Deduplicate by event_id.
Keep GET /jobs/{uuid}/status or GET /jobs/{uuid}/result as a fallback if webhook delivery was delayed.

Webhooks

On this page