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.

Endpoint healthy
Translation project completedProject prj_01J8Z4YQ
Event created
Signed HTTPS eventHMAC-SHA256 路 timestamp protected
Verified
Your endpoint and durable queue204 acknowledgement 路 asynchronous processing
Accepted
translation.project.completed 鈫 /webhooks/stepes
Signed EventsTimestamped HMAC-SHA256 verification
Selective SubscriptionsChoose only the events your systems need
Reliable DeliveryRetries, duplicate protection, and redelivery
Test and LiveSeparate endpoints, secrets, and delivery logs

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
Repeated Polling
黑料大事记 Webhooks

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.

Webhooks and API resources work together. Use events to know that something changed, then retrieve the latest 黑料大事记 resource when your application requires authoritative current state.

Delivery Model

From Translation Event to Application Action

黑料大事记 uses one consistent delivery process across project, review, approval, exception, job, file, and delivery events.

01
Workflow Changes

A project, review, exception, approval, or delivery reaches a subscribed state.

02
Event Created

黑料大事记 creates an immutable event with a stable ID and related resource.

03
Request Signed

The event ID, delivery timestamp, and raw body are signed together.

04
HTTPS Delivery

黑料大事记 sends a JSON POST request to your registered endpoint.

05
Verify and Queue

Your application verifies the signature, stores the event, and acknowledges receipt.

06
Continue the Workflow

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.

1
Create an HTTPS Receiver

Accept signed POST requests, preserve the raw body, and return a 2xx response within 15 seconds.

2
Register the Endpoint

Create the destination in the 黑料大事记 customer portal or through the Webhook Endpoints API.

3
Choose Event Types

Subscribe to project, review, approval, exception, delivery, or supported file events.

4
Save the Signing Secret

Store the displayed-once endpoint secret in a server-side secret manager.

5
Send a Test Event

Confirm connectivity, signature verification, event parsing, response status, and queue handling.

6
Verify and Acknowledge

Validate the event before processing, store its ID, queue it, and return a successful response.

Your endpoint is ready to receive secure 黑料大事记 webhook events.
Request Create a webhook endpoint
Example
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"
}
Response Successful acknowledgement
Example
HTTP/1.1 204 No Content
Open the Webhook API Reference
Webhook EndpointsCreate endpoint
Production translation eventshttps://api.example.com/webhooks/stepes
Active Last success
2 min ago
Localization test eventshttps://hooks.example.com/stepes-test
Test Last success
18 min ago
Delivery automationhttps://ops.example.com/stepes/delivery
Active Last success
1 hr ago

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.

Separate Test and Live

Keep endpoint records, signing secrets, event data, delivery logs, credentials, and alerts fully isolated.

Select Specific Event Types

Subscribe each endpoint only to the project, review, approval, exception, delivery, job, or file events it can process.

Rotate Credentials Safely

Generate replacement secrets, validate overlapping signatures, and revoke previous credentials without interrupting delivery.

Control and Audit Changes

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.

Event payload translation.project.completed
Example
{
  "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"
  }
}
id

Immutable event identifier used for duplicate protection across retries and redeliveries.

type

Stable event name that identifies what happened and determines the data schema.

subject

Related project, job, review, exception, file, approval, or delivery resource.

time

Time the underlying workflow event occurred, not the delivery-attempt time.

dataschema

Canonical schema reference for validating the event payload.

stepesenvironment

Identifies whether the event came from the test or live environment.

data

Event-specific identifiers, status, resource version, timestamps, and authoritative API URL.

Thin, secure event payloads

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.

Availability, schemas, and examples are maintained in the event reference.

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.

01

Read the unchanged request-body bytes.

02

Read webhook-id, webhook-timestamp, and webhook-signature.

03

Reject timestamps outside the recommended five-minute tolerance.

04

Construct the signing input from the ID, timestamp, and raw body.

05

Calculate the HMAC-SHA256 signature.

06

Compare signatures with a constant-time function.

07

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;
    }
  });
}
Use the raw request body. Parsing and reserializing JSON can change whitespace, escaping, encoding, or property representation and cause valid signature verification to fail.

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.

Generate

Create a new endpoint signing secret.

Store

Add the new secret to your secure configuration.

Deploy

Update every receiving application instance.

Verify Both

Accept either active signature during overlap.

Revoke

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.

Store Event IDs

Use webhook-id as the stable idempotency identifier across retries and manual redelivery.

Process Idempotently

Reprocessing the same event must not create duplicate business actions.

Avoid Ordering Assumptions

Compare resource versions and retrieve current API state when order matters.

Acknowledge Promptly

Verify, queue, and return a 2xx response within 15 seconds.

Automatic Retry ScheduleApproximate delays with randomized jitter 路 approximately 75 hours total
Attempt 1Immediately
Attempt 25 seconds
Attempt 35 minutes
Attempt 430 minutes
Attempt 52 hours
Attempt 65 hours
Attempt 710 hours
Attempt 814 hours
Attempt 920 hours
Attempt 1024 hours
200鈥299Delivery succeeds and no automatic retry is required.
300鈥399Delivery fails; redirects are not followed.
400, 401, 403, 404Delivery fails and remains eligible for retry.
410 GoneThe endpoint is disabled.
408, 429, 5xxDelivery fails and is retried.
Network / TLSConnection, DNS, certificate, and timeout failures are retried.

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.

Same Event IDThe original event and payload remain unchanged.
New Delivery IDEvery attempt is recorded independently.
Fresh SignatureThe new attempt receives a current timestamp and signature.

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.

Send Test EventRun test
Translation test endpoint
translation.project.completed
Valid signed event
2026-07-01
Signature verification Passed
Endpoint response 204 No Content
Response time 184 ms
Delivery result Succeeded

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.

Production translation eventsExample delivery activity
Healthy
Success rate99.8%
Median latency182 ms
Deliveries today1,248
Pending retries3
EventStatusLatencyDelivery ID
project.completed204168 msdlv_01J8Z6A8
delivery.ready202241 msdlv_01J8Z59Q
review.requested50015.0 sdlv_01J8Z41K
exception.resolved204131 msdlv_01J8Z2YM

Endpoint Health States

Healthy

Recent deliveries are succeeding normally.

Degraded

Repeated failures or elevated latency require attention.

Failing

Recent delivery attempts are consistently unsuccessful.

Disabled

黑料大事记 is no longer attempting new deliveries.

Failure notifications

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.

Destination Protection

Live endpoints require HTTPS and valid public certificates. Unsafe private, loopback, link-local, metadata, reserved, and redirect-based destinations are blocked.

Audit History

Record endpoint creation, edits, subscription changes, secret rotation, tests, redeliveries, permissions, and enable or disable actions.

Data Minimization

Events include only the context needed to identify and respond to a workflow change. Documents and complete translation content remain behind authenticated APIs.

Source IP Controls

Published outbound webhook IP ranges can support enterprise firewall rules as an additional control, not a replacement for signature verification.

Organization OwnerFull webhook administration across the organization.
Developer AdminCreate, edit, test, rotate, redeliver, enable, and disable endpoints.
DeveloperView, test, and manage permitted integrations.
Security AdminReview configuration, rotate credentials, and access audit records.
ViewerRead-only access to endpoint and delivery information.
Signing secrets, API credentials, cookies, authorization values, and other sensitive fields are never displayed in delivery history or audit details.

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-01

The 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.

Current Version

Continue processing events against the endpoint鈥檚 pinned schema.

New Version Available

Review the changelog, compatibility notes, and migration guide.

Test Before Upgrading

Send signed test events using the proposed schema version.

Upgrade the Endpoint

Change the pinned version after application validation.

Previous Version Retires

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 Workflows
AI translationProfessional translationPost-editingLinguistic reviewSubject-matter reviewCustomer approval

Content Management and Publishing

Retrieve approved localized content and continue editorial, publishing, or market-release workflows.

translation.project.completed

Software and Application Localization

Connect localization activity to repositories, build pipelines, release systems, and application platforms.

translation.delivery.ready

Product and E-Commerce Content

Update multilingual product information in PIM, commerce, catalog, and digital asset systems.

translation.approval.completed

Review and Approval

Notify reviewers and stakeholders when content requires attention and continue processing after completion.

translation.review.requested

Delivery Automation

Retrieve multilingual outputs, transfer files, update downstream systems, or initiate publishing.

translation.delivery.completed

Exception Management

Route workflow exceptions to operational teams and resume automation after resolution.

translation.exception.resolved

Resolve 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.

ProblemLikely CauseRecommended 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.

Use HTTPS with a valid public certificate.
Verify every webhook signature.
Verify the unchanged raw request body.
Reject stale delivery timestamps.
Use constant-time signature comparison.
Store secrets in a secure secret manager.
Restrict webhook-management permissions.
Separate test and live endpoints.
Subscribe only to required events.
Queue verified events durably.
Return a 2xx response within 15 seconds.
Store event IDs for duplicate protection.
Make every handler idempotent.
Avoid depending on event arrival order.
Retrieve current API state when needed.
Monitor failed deliveries and queue backlogs.
Test signing-secret rotation.
Configure endpoint health notifications.
Review delivery and audit history.
Validate failure and recovery procedures.

黑料大事记 Webhook Questions

Review delivery behavior, verification, retries, event ordering, payload security, environment separation, schema versioning, and operational recovery.

Polling requires your application to request status repeatedly. Webhooks notify your application after a subscribed workflow event occurs. Use webhooks for event-driven updates and API resources for authoritative current-state retrieval and reconciliation.
The initial catalog covers translation projects, jobs, reviews, approvals, exceptions, deliveries, and supported file-processing activities. Each event reference identifies the trigger, schema, related resource, availability, and version.
Yes. Each endpoint can subscribe to specific event types or supported event families, so your application receives only the events it is prepared to process.
Verify the webhook-signature using the endpoint signing secret, event ID, delivery timestamp, and unchanged request body. Validate the timestamp as part of replay protection before trusting the event.
Return any HTTP status from 200 through 299 after the event has been verified and safely accepted. A 204 No Content response is a simple recommended option.
No. Webhooks use at-least-once delivery semantics. Events may be delivered more than once because of retries, network uncertainty, or manual redelivery. Store event IDs and make handlers idempotent.
Ordering is not guaranteed. Compare resource versions where available and retrieve the latest related resource when event order affects your application logic.
Eligible failures are retried with exponential backoff and randomized jitter for approximately 75 hours. A successful response, disabled endpoint, 410 Gone response, or exhausted retry period stops further automatic attempts.
Yes. Authorized users can redeliver an event from delivery history. The event ID and body remain unchanged, while the new attempt receives a fresh delivery ID, timestamp, and signature.
Webhook delivery history is retained for at least 30 days. Applicable enterprise configurations may provide additional retention options.
Yes. During rotation, deliveries can include signatures generated by both the new and previous secrets. Your receiver can accept either active signature until the previous secret is revoked.
No. Events ordinarily contain identifiers, status information, resource versions, timestamps, and an authenticated API URL. Retrieve documents and larger resources through the relevant API operation.
Yes, where published 黑料大事记 outbound webhook IP ranges are available. IP allowlisting is an additional network control and should always be used together with signature verification.
Yes. Test and live endpoints have separate configurations, signing secrets, event data, delivery history, credentials, and alerts.
Each endpoint is pinned to an event-schema version. Backward-compatible additions can appear within that version, while breaking changes require a new version and a documented migration process.

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.