Request

Response

    Webhooks

    When you successfully submit a POST job request to APS, the Model Derivative service initiates a translation job. Depending on the complexity and size of the model, it may take a while for the job to finish.

    Rather than periodically checking the translation status with GET manifest, you can use a webhook to be notified when the status of a translation job changes or when the job is complete.

    A webhook is a way for APS to send your application an HTTP POST request when an event occurs. This eliminates the need for your application to periodically check whether an event you are interested in has occurred. Since webhooks can notify you of events in near real-time, webhooks are preferred over polling.

    Before you start using webhooks, you must register (or create) a webhook in APS. When you register a webhook, you provide the following information:

    1. The service the webhook is created for, which is the derivative service for Model Derivative events.
    2. The URL to send the HTTP POST request to (the callback URL).
    3. The event to monitor.
    4. The resource to monitor (the scope).

    For Model Derivative events, the webhook scope is a workflow ID designated by your application. The workflow ID identifies a set of translation jobs that belong to the same workflow. To receive notifications for translation jobs in that workflow, specify the same workflow ID when submitting each job with POST job.

    For example, if you create a webhook with a scope containing the workflow ID my-workflow-id, specify my-workflow-id as the misc.workflow value when submitting a translation job.

    For a step-by-step example, see Creating a Webhook (Model Derivative Events).

    For more information about creating and managing webhooks, see the Webhooks API documentation.

    Handling Callbacks

    When a Model Derivative event matching your webhook subscription occurs, APS sends an HTTP POST request to your application’s callback URL.

    The request contains a JSON payload. The payload differs depending on the event, and your application must handle the appropriate payload. The event documentation provides the schema of the payload as well as an example.

    Model Derivative supports the following webhook events:

    SystemEventDescription
    derivative extraction.finished When a translation job is completed.
    derivative extraction.updated When the status of a translation job is updated.