Core API

Webhooks & Signature Verification

Receive signed terminal job callbacks with webhookUrl. Verify X-E2X-Timestamp and X-E2X-Signature (HMAC-SHA256), handle 5-attempt exponential backoff retries, and meet HTTPS SSRF rules.

Submitting with webhookUrl

Pass a webhookUrl field when calling POST /v1/jobs/submit to receive an outbound HTTP POST request as soon as the job reaches completed or failed.

HTTPS & SSRF Protection Rules

E2X validates webhookUrl at submission time and rejects non-compliant URLs with 400 INVALID_WEBHOOK_URL:

  • Protocol must be https:// (plain HTTP is rejected).
  • Loopback targets (localhost, 127.0.0.1, ::1) are blocked.
  • Private RFC 1918 and link-local IPv4 ranges (10.*, 172.16–31.*, 192.168.*, 169.254.*) and .internal / .local hostnames are blocked.

Webhook Headers & Payload Schema

HeaderValue / Format
Content-Typeapplication/json
User-AgentE2X-API-Platform/1.0
X-E2X-TimestampUnix epoch timestamp in seconds as a string (for example "1794571208").
X-E2X-SignatureHex-encoded HMAC-SHA256 digest prefixed with "sha256=" computed over "${timestamp}.${rawBody}".
JSONTerminal Webhook Payload (Completed & Failed Shapes)
// Completed job callback
{
  "jobId": "job_01JX9R8P3M2W0F7H",
  "requestId": "req_4b2c71f9",
  "status": "completed",
  "output": "https://assets.e2x.ai/outputs/job_01JX9R8P3M2W0F7H.png",
  "error": null,
  "completedAt": "2026-11-13T12:00:08.000Z"
}

// Failed job callback (sanitized error)
{
  "jobId": "job_01JX9R99ABCD",
  "requestId": "req_7e2011ab",
  "status": "failed",
  "output": null,
  "error": {
    "code": "GENERATION_FAILED",
    "message": "Generation failed upstream; your credits were refunded."
  },
  "completedAt": "2026-11-13T12:01:12.000Z"
}

Verifying Signatures (HMAC-SHA256)

Always compute the HMAC-SHA256 digest using the raw unparsed request body string and the X-E2X-Timestamp header joined with a dot: ${timestamp}.${rawBody}. Reject timestamps outside a replay tolerance window (for example 300 seconds) and compare signatures with a constant-time function.

TypeScriptverify-webhook.ts
import crypto from 'node:crypto';

export function verifyE2XWebhook(
  rawBody: string,
  timestampHeader: string | undefined,
  signatureHeader: string | undefined,
  secret: string,
  maxSkewSeconds = 300,
): boolean {
  if (!timestampHeader || !signatureHeader || !secret) return false;

  const ts = Number.parseInt(timestampHeader, 10);
  if (!Number.isFinite(ts)) return false;

  const nowSeconds = Math.floor(Date.now() / 1000);
  if (Math.abs(nowSeconds - ts) > maxSkewSeconds) return false;

  const expected =
    'sha256=' +
    crypto
      .createHmac('sha256', secret)
      .update(`${timestampHeader}.${rawBody}`)
      .digest('hex');

  const expectedBuf = Buffer.from(expected, 'utf8');
  const receivedBuf = Buffer.from(signatureHeader, 'utf8');
  if (expectedBuf.length !== receivedBuf.length) return false;

  return crypto.timingSafeEqual(expectedBuf, receivedBuf);
}
Pythonverify_webhook.py
import hmac
import hashlib
import time

def verify_e2x_webhook(
    raw_body: str,
    timestamp_header: str,
    signature_header: str,
    secret: str,
    max_skew_seconds: int = 300,
) -> bool:
    if not timestamp_header or not signature_header or not secret:
        return False

    ts = int(timestamp_header)
    if abs(int(time.time()) - ts) > max_skew_seconds:
        return False

    signed_payload = f"{timestamp_header}.{raw_body}".encode("utf-8")
    digest = hmac.new(secret.encode("utf-8"), signed_payload, hashlib.sha256).hexdigest()
    expected = f"sha256={digest}"

    return hmac.compare_digest(expected, signature_header)
Goverify_webhook.go
package webhooks

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"math"
	"strconv"
	"time"
)

func VerifyE2XWebhook(rawBody, timestampHeader, signatureHeader, secret string) bool {
	if timestampHeader == "" || signatureHeader == "" || secret == "" {
		return false
	}

	ts, err := strconv.ParseInt(timestampHeader, 10, 64)
	if err != nil {
		return false
	}
	if math.Abs(float64(time.Now().Unix()-ts)) > 300 {
		return false
	}

	mac := hmac.New(sha256.New, []byte(secret))
	mac.Write([]byte(timestampHeader + "." + rawBody))
	expected := "sha256=" + hex.EncodeToString(mac.Sum(nil))

	return hmac.Equal([]byte(expected), []byte(signatureHeader))
}

Timeouts & Exponential Backoff Retries

Your webhook handler must return a 2xx HTTP status within the 10-second request timeout. Non-2xx responses and network timeouts trigger up to 5 total attempts using a 4x exponential backoff schedule (1 second base delay):

AttemptDelay Before AttemptCumulative Elapsed Window
Attempt 1Immediate (0s)0s (10s HTTP timeout)
Attempt 21 second~1s
Attempt 34 seconds~5s
Attempt 416 seconds~21s
Attempt 5 (final)64 seconds~85s before marked permanently failed

If all 5 attempts fail, the job remains accessible via GET /v1/jobs/:jobId so you can always reconcile outputs via polling as a fallback.