Guide · Webhooks

You do not wait for the result. The result comes to you.

Q: Do I need my own server?

You need a public https address that receives the message. It can be a server of yours, a cloud function or a service in your platform: anything that accepts a request and answers "received".

Q: Can I receive the same result twice?

It can happen. That is why you should store the ID, the transactionId, and drop the messages you already processed.

A webhook is an address in your system where we send the result when it is ready. This is how our IMSS queries work: you send the request, you get a receipt right away, and the result arrives on its own.

Request access → See the technical reference ›

immediate receiptresult at your addressup to 3 delivery attempts

Technical questions? Talk to an engineer on WhatsApp — 0% bots.

webhookSTEP BY STEP

Follow the path of a query:

The query ID is called transactionId and it is the same in the receipt and in the result.

In plain words

It is like ordering takeout.

You do not stand at the counter until it is ready. You get a ticket, do something else, and they call you. A webhook is exactly that, between two systems.

⏳

Without a webhookYour system asks and waits for the answer with the line open. If the query takes a while, your user waits in front of a frozen screen.

✓

With a webhookYour system asks, gets a receipt and carries on. When the result is ready, we bring it to you.

The ID is your ticketThe receipt carries an ID, the transactionId. The result arrives with that same ID: that is how you know which query it belongs to.

What your system needs

Four things, nothing more.

What	Why
A public address	An `https` URL we can reach from the internet. The result arrives there.
Answer "received" as soon as it arrives	Reply with a `2xx` code when the message arrives and process it afterwards. That way the attempt does not time out.
Recognize repeated messages	The same result can arrive more than once. Use the `transactionId` so you do not process it twice.
Recognize that it is us	When you create the query you can send your own headers, for example a token. We include them in the call to your webhook so you can authenticate it.

Delivery and billing

The rules, no fine print.

Up to 3 attemptsRight away, one minute later and five minutes later. An attempt fails if your address does not answer 2xx within 10 seconds. We do not follow redirects.

Charged when there is a resultThe receipt is free. Credits are charged once, when the query resolves, and the billable field tells you whether that result counted.

⚑

Your address is your responsibilityThe result is charged even if your webhook could not receive it. That is why it should always be available.

Fallback for contribution weeksFor that service, if your webhook failed, you can fetch the result with the ID for 24 hours, at no cost.

For your technical team

A receiver in ten lines.

This is everything a webhook needs to work well: recognize the call, answer right away, drop repeats and decide with type.

Answer first, process laterThe 2xx goes before your business logic.

The usual formatThe body is the standard envelope: status, type, message, data, transactionId and billable.

Input errors are reported right awayAn invalid request gets INVALID_REQUEST in the same call, not at the webhook, and is not charged.

See the technical reference ↗

tu-webhook
          
          
        
app.post("/hooks/origoid", express.json(), (req, res) => {
  // 1. is it from OrigoID? compare the token you sent
  if (req.get("authorization") !== `Bearer ${process.env.WEBHOOK_TOKEN}`)
    return res.sendStatus(401);

  res.sendStatus(200);                    // 2. answer "received"

  const r = req.body;
  if (alreadyProcessed(r.transactionId)) return;  // 3. drop duplicates
  process(r.type, r.data);               // 4. decide with type
});@app.post("/hooks/origoid")
def origoid_webhook():
    # 1. is it from OrigoID? compare the token you sent
    if request.headers.get("Authorization") != f"Bearer {WEBHOOK_TOKEN}":
        return "", 401

    r = request.get_json()
    if not already_processed(r["transactionId"]):   # 3. drop duplicates
        enqueue(r["type"], r["data"])          # 4. decide with type

    return "", 200                           # 2. answer "received"What arrives at your webhook
{
  "status": "OK",
  "type": "SUCCESS",
  "message": "NSS found",
  "data": { "nss": "00000000000" },
  "transactionId": "39b972d3-20a8-539a-acfb-70657588df9b",
  "billable": true
}

Frequently asked

What people usually ask us.

What is a webhook?

An address in your system that receives messages. Instead of you asking again and again whether the result is ready, we send it to that address as soon as it is.

Do I need my own server?

You need a public https address that receives the message. It can be a server of yours, a cloud function or a service in your platform: anything that accepts a request and answers "received".

How do I know the message comes from OrigoID?

When you create the query you can include your own headers, for example a secret token. We send them back in the call to your webhook and you check that they match.

What happens if my address is down?

We try three times: right away, after one minute and after five minutes. If all three fail, the result is not sent again. For contribution weeks you can fetch it with the ID for 24 hours.

Am I charged if my webhook did not receive the result?

Yes. The credit is charged when the query resolves, whether or not your address received it, because the query was made. The initial receipt is never charged.

Can I receive the same result twice?

It can happen. That is why you should store the ID, the transactionId, and drop the messages you already processed.