Overview

After configuring the CallbackUrl on the AppId settings page in the console, the server will send a POST request to the CallbackUrl whenever an envelope status changes. > ⚠️ Note: All callbacks are POST requests. If you receive a GET request, please check whether your CallbackUrl has an HTTP-to-HTTPS 301/302 redirect.

Configuration

1. Log in to the console, go to 'App Management' → select the target AppId
2. In the 'Callback Configuration' section, fill in the CallbackUrl (must be a publicly accessible HTTPS address)
3. After saving, the system generates a 32-character CallbackKey (Base62) for encrypting/decrypting callback data
4. Keep the CallbackKey safe. If lost, regenerate it (the old key is invalidated immediately)

⚠️CallbackUrl must use HTTPS
CallbackUrl must be publicly accessible (no internal IPs or localhost)
Each AppId can have multiple CallbackUrls, each with its own CallbackKey
Different CallbackUrls use independent CallbackKeys

Data Format & Encryption

{
  "encrypt": "dGhpcyBpcyBhIGJhc2U2NCBlbmNvZGVkIGV4YW1wbGU..."
}

Encryption Algorithm

Algorithm

AES-256-GCM

Key

32 bytes (256 bits)

Nonce

12 bytes (96 bits, randomly generated)

Ciphertext Format

Base64( nonce[12 bytes] + GCM_ciphertext + GCM_tag[16 bytes] )

Decryption Steps

1. Extract the encrypt field from the request body
2. Base64-decode to get raw bytes
3. First 12 bytes = nonce, remainder = GCM ciphertext (includes 16-byte auth tag)
4. Use CallbackKey (32 bytes, UTF-8) to create AES-256-GCM decryptor
5. GCM.Open(nonce, ciphertext) to decrypt to JSON plaintext
6. Deserialize JSON to EnvelopeCallbackPayload

Delivery Policy

HTTP Timeout

5 seconds (HTTP request timeout)

Success Condition

Client returns HTTP 200 within 5 seconds

Max Retries

Retry Schedule

1s, 2s, 3s, 4s, 5s → 10s, 15s, 20s, 25s, 30s, 35s, 40s, 45s, 50s, 55s → 1min, 2min, 3min, 4min, 5min, 6min, 7min, 8min, 9min, 10min → 15min, 25min, 35min, 45min, 55min → 1h, 2h, 3h, 4h, 5h, 6h

Ordering

Callbacks for the same envelope + integration are delivered in event order

ℹ️Retry intervals grow with attempt count. Once HTTP 200 is received, the platform stops re-sending this callback. After 36 failed retries, the platform considers the message undeliverable and discards it.

Best Practices

💡

Keep CallbackKey secure; use environment variables or a secrets manager instead of hardcoding
Keep callback handling lightweight; return HTTP 200 within 5 seconds; process complex logic asynchronously
Implement idempotent handling, as the same event may be delivered more than once in edge cases
Log all callback events for troubleshooting
Use EnvelopeId + EventType + OccurredAt to determine event uniqueness

Get Envelope Download Info Envelope Events