Webhooks

Receive callback notifications when transcripts complete, are verified, or get a new version.

Webhooks let Trint notify your application when something happens, instead of you having to poll the API. When you register a callback URL, Trint sends an HTTP POST request to your endpoint each time a subscribed event occurs — for example, when a transcript finishes transcribing.

How it works

You register a callback URL and a list of event subscriptions with Trint.
When a subscribed event happens, Trint sends an HTTP POST request to your callback URL with a JSON payload describing the event.
Your endpoint processes the payload and responds with 200 OK.

Polling vs. webhooks

Webhooks are the recommended alternative to polling the Transcripts API for status changes. Instead of repeatedly asking Trint whether a transcript is ready, let Trint tell you the moment it is.

Registering a webhook

Register your endpoint by sending a PUT request to the Webhooks API, authenticated with Basic Authentication. Provide the URL Trint should call and the events you want to subscribe to.

cURL

curl --request PUT \
  -u "AK-12345ABCDE:this15SECRET_CXJK3ctglt6LOpYxRmZ" \
  --url 'https://api.trint.com/callbacks/transcript/' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --data '{
    "callbackUrl": "https://webhook.example.com/trint-callback",
    "callbackSubscriptions": ["TRANSCRIPT_COMPLETE", "TRANSCRIPT_VERIFIED"]
  }'

See the Webhooks API reference for the full request and response schema, including how to de-register an endpoint.

Event types

You subscribe to one or more of the following events when you register your callback URL:

Event	Dispatched when
`TRANSCRIPT_COMPLETE`	An uploaded or realtime file finishes transcribing.
`TRANSCRIPT_VERIFIED`	A transcript has been fully verified in the editor. Also applies to transcripts shared with you.
`TRANSCRIPT_NEW_VERSION` (beta)	A new transcript version is created. Also applies to transcripts shared with you. Available from 10 Feb 2025.

Payload

Each event is delivered as a JSON body in the POST request to your callback URL. The example below shows a TRANSCRIPT_COMPLETE payload:

json

{
  "eventType": "TRANSCRIPT_COMPLETE",
  "transcriptId": "<TRINT_ID>",
  "title": "myFile.mp4",
  "user": "user@me.com",
  "metadata": "some opaque metadata string"
}

Field	Description
`eventType`	The event that was dispatched, e.g. `TRANSCRIPT_COMPLETE`.
`transcriptId`	The ID of the affected transcript. Use it to fetch content from the Transcripts API.
`title`	The transcript's title.
`user`	The email address of the user the transcript belongs to.
`metadata`	The opaque metadata string you supplied when uploading the file. Omitted from `TRANSCRIPT_NEW_VERSION` payloads.

Passing metadata through

The metadata field echoes back the opaque string you provided at upload time. Use it to correlate the callback with a record in your own system without an extra lookup.

Responding to events

Your endpoint should return 200 OK as soon as it has accepted the payload. Do any slow processing asynchronously so Trint receives a prompt response.

Acknowledge quickly, then process

If your endpoint is slow to respond or returns a non-2xx status, the delivery is treated as failed. Acknowledge the request with 200 OK first, then handle the work in the background.

Next steps

Webhooks API reference — register and de-register endpoints, full schema.
Transcripts API — fetch transcript content once you receive an event.
API Keys & Authentication — authenticate your registration requests.