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/.localhostnames are blocked.
Webhook Headers & Payload Schema
| Header | Value / Format |
|---|---|
Content-Type | application/json |
User-Agent | E2X-API-Platform/1.0 |
X-E2X-Timestamp | Unix epoch timestamp in seconds as a string (for example "1794571208"). |
X-E2X-Signature | Hex-encoded HMAC-SHA256 digest prefixed with "sha256=" computed over "${timestamp}.${rawBody}". |
// 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.
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);
}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)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):
| Attempt | Delay Before Attempt | Cumulative Elapsed Window |
|---|---|---|
| Attempt 1 | Immediate (0s) | 0s (10s HTTP timeout) |
| Attempt 2 | 1 second | ~1s |
| Attempt 3 | 4 seconds | ~5s |
| Attempt 4 | 16 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.