Developer Platform
Webhooks
Receive secure, signed events when 黑料大事记 translation projects, jobs, reviews, approvals, exceptions, and deliveries change. Subscribe to the events your application needs and connect asynchronous translation workflows to your content, product, and business systems.
Automate Translation Workflows With Event-Driven Updates
Translation workflows often continue after the initial API request. Files may require preparation, content may move through AI translation or professional human translation, reviewers may need to provide feedback, and multilingual deliverables may become available at different times.
黑料大事记 webhooks notify your application as these workflow events occur, so your systems can respond without repeatedly checking every active project.
- Update project records
- Notify reviewers
- Retrieve deliverables
- Resume build workflows
- Escalate exceptions
- Synchronize dashboards
Your application repeatedly requests status.
黑料大事记 sends an event after a subscribed change.
Updates depend on the polling interval.
Events are delivered shortly after they are created.
Requests continue when nothing changed.
Requests occur only for relevant workflow events.
Your application initiates every check.
黑料大事记 initiates the event notification.
Useful for current-state retrieval.
Useful for workflow automation and timely response.
Delivery Model
From Translation Event to Application Action
黑料大事记 uses one consistent delivery process across project, review, approval, exception, job, file, and delivery events.
A project, review, exception, approval, or delivery reaches a subscribed state.
黑料大事记 creates an immutable event with a stable ID and related resource.
The event ID, delivery timestamp, and raw body are signed together.
黑料大事记 sends a JSON POST request to your registered endpoint.
Your application verifies the signature, stores the event, and acknowledges receipt.
Background processing retrieves current resources and performs the next action.
Receive Your First 黑料大事记 Event
Create an endpoint, subscribe to a workflow event, and validate a signed test delivery before enabling production traffic.
Accept signed POST requests, preserve the raw body, and return a 2xx response within 15 seconds.
Create the destination in the 黑料大事记 customer portal or through the Webhook Endpoints API.
Subscribe to project, review, approval, exception, delivery, or supported file events.
Store the displayed-once endpoint secret in a server-side secret manager.
Confirm connectivity, signature verification, event parsing, response status, and queue handling.
Validate the event before processing, store its ID, queue it, and return a successful response.
POST /v2/webhook-endpoints
Authorization: Bearer {access_token}
Content-Type: application/json
{
"url": "https://example.com/webhooks/stepes",
"description": "Translation test endpoint",
"environment": "test",
"event_types": [
"translation.project.completed",
"translation.project.failed",
"translation.delivery.ready"
],
"event_schema_version": "2026-07-01"
}
HTTP/1.1 204 No Content
Endpoint Management
Configure Webhooks for Your Applications and Environments
Create separate endpoints for different applications, departments, environments, or workflow responsibilities. Manage them through the 黑料大事记 customer portal or the Webhook Endpoints API.
Keep endpoint records, signing secrets, event data, delivery logs, credentials, and alerts fully isolated.
Subscribe each endpoint only to the project, review, approval, exception, delivery, job, or file events it can process.
Generate replacement secrets, validate overlapping signatures, and revoke previous credentials without interrupting delivery.
Apply role-based permissions and record endpoint edits, tests, redeliveries, rotations, and enable or disable actions.
Event Structure
A Consistent Structure for Every Event
Every 黑料大事记 webhook uses a common event envelope so your application can identify, route, log, validate, and process translation workflow events consistently.
{
"specversion": "1.0",
"id": "evt_01J8Z5T6M5A4K2QH7B9R3C1D0E",
"source": "https://api.stepes.com/v2/projects/prj_01J8Z4YQ",
"type": "translation.project.completed",
"subject": "projects/prj_01J8Z4YQ",
"time": "2026-07-21T16:20:00Z",
"datacontenttype": "application/json",
"dataschema": "/developers/webhooks/schemas/translation.project.completed/1",
"stepesenvironment": "live",
"stepesschemaversion": "1",
"data": {
"project_id": "prj_01J8Z4YQ",
"status": "completed",
"resource_version": 42,
"resource_url": "https://api.stepes.com/v2/projects/prj_01J8Z4YQ",
"completed_at": "2026-07-21T16:20:00Z"
}
}
idImmutable event identifier used for duplicate protection across retries and redeliveries.
typeStable event name that identifies what happened and determines the data schema.
subjectRelated project, job, review, exception, file, approval, or delivery resource.
timeTime the underlying workflow event occurred, not the delivery-attempt time.
dataschemaCanonical schema reference for validating the event payload.
stepesenvironmentIdentifies whether the event came from the test or live environment.
dataEvent-specific identifiers, status, resource version, timestamps, and authoritative API URL.
Webhooks contain the context needed to understand and route a workflow change. Source files, translated files, complete translation content, credentials, and large binary resources remain behind authenticated API operations.
Event Catalog
Subscribe Only to the Translation Events You Need
Event names describe completed facts and use a stable hierarchical format. Select individual events or supported event families for each endpoint.
Project Events
translation.project.createdA project is successfully created.translation.project.acceptedThe project passes initial validation.translation.project.startedTranslation workflow processing begins.translation.project.completedAll required project work is complete.translation.project.failedThe project reaches a terminal failure state.translation.project.canceledThe project is canceled.translation.project.updatedCustomer-visible project information changes materially.Review and Approval Events
translation.review.requestedProfessional or customer review is required.translation.review.completedReview work is completed.translation.review.reopenedA completed review is reopened.translation.approval.requestedA designated approval is required.translation.approval.completedApproval is granted.translation.approval.rejectedApproval is rejected.Exception Events
translation.exception.createdA customer-visible exception requires attention.translation.exception.updatedThe exception changes materially.translation.exception.resolvedThe exception is resolved.Delivery Events
translation.delivery.readyMultilingual deliverables are available for retrieval.translation.delivery.startedDelivery preparation or transfer begins.translation.delivery.completedDelivery completes successfully.translation.delivery.failedDelivery cannot be completed.translation.delivery.expiredA time-limited delivery is no longer available.Job Events
translation.job.createdA language or workflow job is created.translation.job.startedProcessing begins for the job.translation.job.completedThe job completes successfully.translation.job.failedThe job reaches a failure state.translation.job.canceledThe job is canceled.File Events
translation.file.acceptedAn uploaded file passes validation.translation.file.rejectedAn uploaded file cannot be accepted.translation.file.processedFile extraction or preparation completes.translation.file.failedFile processing fails.Signature Verification
Verify Every Webhook Before Processing It
Every 黑料大事记 webhook is cryptographically signed so your application can verify its origin and detect changes to the request. Verification uses the event ID, delivery timestamp, raw request body, and the endpoint signing secret.
Read the unchanged request-body bytes.
Read webhook-id, webhook-timestamp, and webhook-signature.
Reject timestamps outside the recommended five-minute tolerance.
Construct the signing input from the ID, timestamp, and raw body.
Calculate the HMAC-SHA256 signature.
Compare signatures with a constant-time function.
Parse and queue the event only after successful verification.
import crypto from "node:crypto";
function verify(rawBody, headers, secret) {
const id = headers["webhook-id"];
const timestamp = headers["webhook-timestamp"];
const supplied = headers["webhook-signature"];
const timestampNumber = Number(timestamp);
if (!id || !supplied || !Number.isInteger(timestampNumber)) return false;
if (Math.abs(Math.floor(Date.now() / 1000) - timestampNumber) > 300) return false;
if (!secret?.startsWith("whsec_")) return false;
const key = Buffer.from(secret.slice(6), "base64");
const message = Buffer.concat([
Buffer.from(id + "." + timestamp + ".", "utf8"),
rawBody
]);
const expected = crypto.createHmac("sha256", key).update(message).digest();
return supplied.trim().split(/\s+/).some((item) => {
const comma = item.indexOf(",");
if (comma < 1 || item.slice(0, comma) !== "v1") return false;
try {
const actual = Buffer.from(item.slice(comma + 1), "base64");
return actual.length === expected.length &&
crypto.timingSafeEqual(actual, expected);
} catch {
return false;
}
});
}
Credential Rotation
Rotate Signing Secrets Without Interrupting Delivery
黑料大事记 supports overlapping signatures so you can deploy a replacement secret, validate it in production, and revoke the previous credential without downtime.
Create a new endpoint signing secret.
Add the new secret to your secure configuration.
Update every receiving application instance.
Accept either active signature during overlap.
Remove the previous secret after validation.
Design for Reliable At-Least-Once Delivery
Events can be delivered more than once, delayed by network conditions, or arrive in a different order from the underlying workflow changes. Build handlers that remain safe under all of these normal conditions.
Use webhook-id as the stable idempotency identifier across retries and manual redelivery.
Reprocessing the same event must not create duplicate business actions.
Compare resource versions and retrieve current API state when order matters.
Verify, queue, and return a 2xx response within 15 seconds.
Manual Redelivery
Recover a Missed Event Without Creating a New Business Event
Authorized users can redeliver an event after correcting an endpoint or downstream outage.
Webhook Testing
Validate Your Integration Before Going Live
Use signed test events to evaluate your complete receiving workflow without exposing live translation project data. Select a scenario to review the expected validation, response, and recovery behavior.
Delivery Visibility
See What 黑料大事记 Sent and How Your Endpoint Responded
Delivery history helps your team validate integrations, investigate failures, recover from outages, and monitor endpoint health across test and live environments.
| Event | Status | Latency | Delivery ID |
|---|---|---|---|
| project.completed | 204 | 168 ms | dlv_01J8Z6A8 |
| delivery.ready | 202 | 241 ms | dlv_01J8Z59Q |
| review.requested | 500 | 15.0 s | dlv_01J8Z41K |
| exception.resolved | 204 | 131 ms | dlv_01J8Z2YM |
Endpoint Health States
Recent deliveries are succeeding normally.
Repeated failures or elevated latency require attention.
Recent delivery attempts are consistently unsuccessful.
黑料大事记 is no longer attempting new deliveries.
Alert designated administrators when retries are exhausted, an endpoint begins failing, a certificate becomes invalid, or an endpoint is disabled.
Security and Governance
Enterprise Controls for Webhook Operations
Manage event destinations, credentials, payload access, and operational activity across development and production environments.
Live endpoints require HTTPS and valid public certificates. Unsafe private, loopback, link-local, metadata, reserved, and redirect-based destinations are blocked.
Record endpoint creation, edits, subscription changes, secret rotation, tests, redeliveries, permissions, and enable or disable actions.
Events include only the context needed to identify and respond to a workflow change. Documents and complete translation content remain behind authenticated APIs.
Published outbound webhook IP ranges can support enterprise firewall rules as an additional control, not a replacement for signature verification.
Event Versioning
Keep Integrations Stable as Event Schemas Evolve
Pin each endpoint to a documented schema version, test new versions before upgrading, and keep breaking changes separate from backward-compatible additions.
Endpoint-Pinned Schema Version
2026-07-01The pinned version governs event fields, data types, required properties, nullability, nested structures, enumerated values, and event-specific payload schemas.
Consumers should ignore unknown JSON properties so backward-compatible additions do not interrupt processing.
Continue processing events against the endpoint鈥檚 pinned schema.
Review the changelog, compatibility notes, and migration guide.
Send signed test events using the proposed schema version.
Change the pinned version after application validation.
Receive advance notice and a published retirement date for generally available versions.
Integration Patterns
Connect Webhook Events Across Your Content Architecture
Use one event layer to coordinate multilingual content workflows across publishing, product development, software delivery, review, approval, exception management, and enterprise operations.
AI and Human Workflows
One Event Layer Across Automated and Professional Translation
Use the same project, review, approval, exception, and delivery event model while 黑料大事记 applies the workflow appropriate for your content and quality requirements.
Explore AI + Human Translation WorkflowsContent Management and Publishing
Retrieve approved localized content and continue editorial, publishing, or market-release workflows.
translation.project.completedSoftware and Application Localization
Connect localization activity to repositories, build pipelines, release systems, and application platforms.
translation.delivery.readyProduct and E-Commerce Content
Update multilingual product information in PIM, commerce, catalog, and digital asset systems.
translation.approval.completedReview and Approval
Notify reviewers and stakeholders when content requires attention and continue processing after completion.
translation.review.requestedDelivery Automation
Retrieve multilingual outputs, transfer files, update downstream systems, or initiate publishing.
translation.delivery.completedException Management
Route workflow exceptions to operational teams and resume automation after resolution.
translation.exception.resolvedResolve Common Webhook Problems
Use delivery details, event identifiers, endpoint health, and the related API resource to diagnose integration problems without exposing credentials or customer content.
| Problem | Likely Cause | Recommended Resolution |
|---|---|---|
| Signature does not match | The request body changed before verification. | Verify the unchanged request-body bytes. |
| Timestamp is rejected | Server clock drift or a delayed replay. | Synchronize server time and inspect the delivery timestamp. |
| Duplicate business actions occur | Processed event IDs are not stored. | Deduplicate all processing with webhook-id. |
| Events appear out of order | Delivery timing differs from event occurrence order. | Compare resource versions and retrieve current API state. |
| Delivery times out | The handler performs synchronous downstream work. | Queue the event and acknowledge it promptly. |
| Endpoint becomes disabled | It returned 410 Gone or was disabled administratively. | Correct the destination and enable it again. |
| Certificate validation fails | The certificate is expired, invalid, or untrusted. | Install a valid publicly trusted certificate. |
| An expected event is missing | The endpoint is not subscribed to the event. | Review endpoint subscriptions and environment. |
Include the endpoint ID, event ID, delivery ID, environment, approximate occurrence time, response status, and a concise description in support requests. Never send signing secrets, API credentials, or sensitive payload data.
Prepare Your Webhook Integration for Production
Complete this operational checklist before enabling live event delivery for your translation workflows.
黑料大事记 Webhook Questions
Review delivery behavior, verification, retries, event ordering, payload security, environment separation, schema versioning, and operational recovery.
Related Documentation
Continue Building With 黑料大事记
Move from webhook implementation to translation project creation, status retrieval, API reference operations, integration architecture, and developer security.
Build Reliable Event-Driven Translation Workflows
Connect your applications to secure 黑料大事记 events and automate translation project updates, reviews, approvals, exceptions, and multilingual content delivery.