AssemblyAI's FDEs watch for the usage spike that goes silent

On Monday, a developer creates an API key and sends a few test recordings. By Wednesday their request count has multiplied. By Friday there are almost no requests at all. On the dashboard the usage line climbs and then drops straight down, and nobody has filed a ticket explaining what happened.

For an FDE Onboarding, that line is a case to work. AssemblyAI describes the role as driving activation of new customers across its product lines.

The person owns the journey from the first API call to steady production use, or more precisely the time between the first call and the first month of production traffic.

The skill here is not knowing your own product. It is working out where a customer is stuck when they don’t say so, getting into their code to unblock it, and stepping away once the system runs smoothly.

The easiest case to picture is a prototype that fetches transcripts by polling, because AssemblyAI’s own documentation warns that this approach will hit rate limits.

Why reach out while usage is still rising?

AssemblyAI’s job posting is explicit: the FDE manages a portfolio of customers in onboarding and must reach out proactively as soon as a developer’s usage rises, to unblock them before they go quiet. The trigger makes sense. Rising usage is when a prototype first meets real load, and that is also when it is most likely to break.

The role is also tied to business results. The posting asks for a track record of “carrying a number”, meaning having owned and hit a target. So don’t treat a support call as finished once it has been answered. The work is done only when the customer is running steadily in production.

A concrete case: a polling prototype breaks under load

Picture a startup building a meeting-notes tool. Their developer writes the prototype the most natural way: upload an audio file, get a transcript ID, then loop every few seconds asking for the status until the result arrives. With ten files this works fine. When they push their whole archive of recordings, things start to break.

The first failure comes from rate limits. AssemblyAI’s documentation says polling a transcript is rate-limited per key and per transcript ID. Exceed the limit and the API returns HTTP 429 with a Retry-After header. If the customer’s code ignores that header and retries immediately, it will keep getting 429s and fill its logs with errors.

The second failure is concurrency. By default, a free account can run only 5 pre-recorded transcription jobs at once, while a paid account gets 200+. Custom limits have to be arranged with Sales or support. A team pushing thousands of files through a free key will see the queue barely move and may easily conclude the API is slow.

The result is that the developer goes quiet. They can’t tell whether the fault lies in their design or with the provider, so they stop trying. Had the FDE reached out on Wednesday, while the usage line was still rising, this could have been stopped at the start.

The fix: replace polling with webhooks

AssemblyAI’s own documentation recommends webhooks to avoid 429s, and describes them as the production approach in place of polling. The customer registers a URL, and AssemblyAI calls it when the transcript is ready. There is one important condition: if the endpoint does not return 2xx within 10 seconds, AssemblyAI resends, up to 10 attempts in total.

Two design rules follow from that condition. The handler must respond quickly, so it must not fetch the transcript, run a summary or write to several tables inside the request. The handler must also be idempotent, meaning that receiving the same event twice still results in processing it once, because a retry can arrive after you have already finished.

For security, webhooks can be authenticated with a custom HTTP header that you set yourself in the request. Webhooks are also sent from fixed IPs, so they can be allowlisted: 44.238.19.20 for the US region and 54.220.25.36 for the EU region.

If the customer’s security team asks where the webhooks come from, those two IP addresses plus the authentication header are the answer to have ready.

The fix you write alongside the customer’s developer might look like this. The header name and payload field names are illustrative only; check them against the current documentation.

from flask import Flask, request, abort
import os

app = Flask(__name__)
SECRET = os.environ["WEBHOOK_SECRET"]

@app.post("/hooks/transcript")
def transcript_done():
    # 1. Authenticate with the custom header you configured when creating the job
    if request.headers.get("X-Webhook-Secret") != SECRET:
        abort(401)
    event = request.get_json(force=True)
    tid = event.get("transcript_id")
    # 2. Idempotent: skip if the ID is already queued or processed
    if not seen_before(tid):      # e.g. INSERT ... ON CONFLICT DO NOTHING
        enqueue_fetch(tid)        # a worker fetches and processes the transcript later
    # 3. Return 2xx immediately, before the 10 seconds run out
    return "", 200

For teams that must keep polling during the migration, the minimum fix is to read Retry-After and wait exactly that long, rather than using a fixed delay. At the same time, check whether they are on a free or paid key. If they need more concurrency, bring Sales in: this is a cross-functional role, working with Sales, Support, Product and Engineering.

Five steps to run an onboarding case yourself

Step one is to watch usage signals rather than wait for tickets. A sudden surge in calls, a run of 429 errors or a free key hitting its concurrency ceiling are all worth a short message asking the customer what they are building.

Step two is to ask to see the code. AssemblyAI expects its FDEs to read unfamiliar customer codebases quickly and ship working fixes with the customer’s engineers, usually in Python or JavaScript/Node services. Thirty minutes reading the code that calls the API often tells you more than an hour-long meeting.

Step three is to fix the layer that is actually breaking. Sometimes it is how results are retrieved (polling or webhooks), sometimes account limits, sometimes networking or the allowlist. Each layer needs different people, so don’t send a ten-item to-do list.

Step four is to test in a staging or test environment, without touching the customer’s production pipeline. Send a duplicate payload, deliberately make the handler take longer than 10 seconds, then read the logs to see how retries play out. Step five is to feed what you learned back to Product and Support, so the next customer doesn’t trip over the same thing.

Common mistakes

The most common mistake is doing all the heavy work inside the webhook handler, going past 10 seconds, and then receiving the same event several times, sometimes producing duplicate notes. The second is treating 429 as the provider’s fault without reading Retry-After.

The third mistake is the FDE’s own: assuming a quiet customer is a happy one. The fourth is sending documentation instead of a fix. A stuck customer needs a pull request, not another link.

How to put this skill on your CV

When reading job descriptions, look for phrases such as activation, first API call to production and carry a number. They signal that the role is measured by whether customers reach production. AssemblyAI’s posting also asks for an understanding of real-time and streaming protocols such as WebSockets and audio pipelines, so if you haven’t worked with them, build a small streaming client to practise.

On a CV, a line such as “moved a customer pipeline from polling to idempotent webhooks, eliminated 429 errors, reached production in two weeks” carries far more weight than a list of frameworks. If you don’t yet have real customers, do the same exercise on a personal project and record the before-and-after numbers.

For the developer at the start of this piece, the opportunity was on Wednesday, while the usage line was still rising. By Friday, once they had gone quiet, bringing them back was much harder.