Webhooks
Completion notification when message generation is finished.
Webhooks
When you request message generation, you can provide a URL to receive a notification as soon as the batch is finished. No separate webhook registration is required.
Required: Webhook secret
You must have generated your webhook secret in your account (next to your API key) in order to receive the completion notification. Without it, the webhook will not be sent.
Completion notification
Prerequisite: Pass completion_notification_url in your Request Message Generation API call. That URL receives a single POST request when the batch is done.
As soon as the final message is generated from the requested batch, the notification is sent to the provided URL. Use the payload to reconcile requested_messages_count vs generated_messages_count and to look up the batch via secure_request_id (e.g. with the Retrieve Messages API).
Example webhook payload
The request body is JSON with the following fields:
| Field | Type | Description |
|---|---|---|
| secure_request_id | string | Unique identifier for the message generation request; use with Retrieve Messages API |
| status | string | Status of the batch (e.g. complete) |
| completed_at | string (ISO 8601) | Timestamp when generation completed (UTC) |
| requested_messages_count | integer | Total number of messages requested in the batch |
| generated_messages_count | integer | Number of messages successfully generated |
Retry behaviour
If your endpoint does not return a success response, Upscale retries the webhook delivery. Respond with a 2xx status within the timeout so the attempt is considered successful.
| Metric | Value |
|---|---|
| Total attempts | 25 (1 initial + 24 retries) |
| Backoff strategy | Exponential with jitter |
| First retry | ~16–46 seconds after initial attempt |
| Last retry | ~21 days after initial attempt |
| Timeout per attempt | 10 seconds |
| Success codes | 200–299 (2xx only) |
| Failure codes (trigger retry) | 3xx, 4xx, 5xx |
Idempotency: The same completion event may be delivered more than once (e.g. on retries). Use webhook_triggered_at (or equivalent) to detect duplicate deliveries and process each event only once.
Signature verification (customer side)
To confirm that a webhook request comes from Upscale, verify the signature before processing. Only process the webhook if the signature matches.
What you need to do:
- Retrieve your webhook secret from the Upscale UI (Account settings).
- When you receive a webhook:
- Use the raw request body (the exact JSON payload as received — do not parse and re-serialize).
- Read the
Upscale-Signatureheader value.
- Compute the expected signature: Use HMAC SHA256 with your webhook secret as the key and the raw body (as bytes) as the message.
- Compare signatures using a timing-safe comparison (e.g. constant-time equals).
- Only process the webhook if the signatures match; otherwise reject the request.
Example payload
{
"secure_request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"status": "complete",
"completed_at": "2024-02-08T11:30:45Z",
"requested_messages_count": 12,
"generated_messages_count": 12
}