About webhooks

As alternative to polling the Sieve API for a job to complete, webhooks allow Sieve to notify your API when results are ready. This eliminates unnecessary requests made by polling, and can get results back faster. In addition, webhooks can be triggered by the Sieve website, which can enable complex workflows with an accessible interface.

Event types

Webhooks can be triggered by the following event types:

  • job_complete - triggered when a job completes successfully or with an error.
  • job_start - triggered when a job has exited the queue and is being processed.

More event types will be added in the future. See the API reference for more response information.

Using webhooks via the HTTP API

The website webhook.site provides a great way to test webhooks. Copy the unique URL presented to you on the website.

Submit a new job by sending a POST request to the /v2/push endpoint:

  curl 'https://mango.sievedata.com/v2/push' \
  -H 'X-API-Key: <your api key>' \
  --data-raw '{
    "function": "sieve/speech_transcriber",
    "inputs": {
        "file": {
          "url": "https://storage.googleapis.com/sieve-public-data/assets/dub.m4a"
      }
     },
    "webhooks": [{
            "type": "<event type>",
            "url": "<your webhook url>"
        }]
  }'

Once the job completes, you’ll receive a notification on webhook.site with the output of the job.

Using webhooks via the Python client

Webhooks can also be set via the Python client with the webhooks parameter.

f = sieve.function.get("...")
f.run(
    target_audio,
    webhooks=[
        {
            "type": "<event type>",
            "url": "<your webhook url>"
        }
    ]
)

The code will run as usual, with the added benefit of a webhook being triggered once the job is complete.

Using webhooks via the Sieve dashboard

Webhooks can also be set on a per-function basis via the dashboard. In other words, every time the function is run (from the UI, REST API, or Python client), the webhook will be triggered. Add the webhook on the Settings page once you have a function selected.

Once you submit a run, you should again receive a notification.

If a list of webhooks is specified via the REST API, this will override any webhooks set on the UI.