Guía · Webhooks

Tú no esperas el resultado. El resultado te avisa.

Q: ¿Necesito un servidor propio?

Necesitas una dirección https pública que reciba el mensaje. Puede ser un servidor tuyo, una función en la nube o un servicio de tu plataforma: cualquier cosa que acepte una petición y conteste "recibido".

Q: ¿Puedo recibir el mismo resultado dos veces?

Puede pasar. Por eso conviene guardar el folio, el transactionId, y descartar los mensajes que ya procesaste.

Un webhook es una dirección de tu sistema a la que enviamos el resultado cuando está listo. Así funcionan nuestras consultas al IMSS: mandas la petición, recibes un acuse de inmediato y el resultado llega solo.

Solicitar acceso → Ver la referencia técnica ›

acuse inmediatoresultado en tu direcciónhasta 3 intentos de entrega

¿Dudas técnicas? Habla con un ingeniero por WhatsApp — 0% bots.

webhookPASO A PASO

Sigue el recorrido de una consulta:

El folio de la consulta se llama transactionId y es el mismo en el acuse y en el resultado.

En palabras simples

Es como pedir comida para llevar.

No te quedas parado en el mostrador hasta que esté lista. Te dan un ticket, haces otra cosa y te avisan. Un webhook es eso mismo entre dos sistemas.

⏳

Sin webhookTu sistema pregunta y se queda esperando la respuesta con la línea abierta. Si la consulta tarda, tu usuario espera frente a una pantalla detenida.

✓

Con webhookTu sistema pregunta, recibe un acuse y sigue con lo suyo. Cuando el resultado está listo, nosotros te lo llevamos.

El folio es tu ticketEl acuse trae un folio, el transactionId. El resultado llega con ese mismo folio: así sabes a qué consulta corresponde.

Qué necesita tu sistema

Cuatro cosas, nada más.

Qué	Por qué
Una dirección pública	Una URL `https` que podamos alcanzar desde internet. Ahí llega el resultado.
Contestar "recibido" en cuanto llegue	Responde con un código `2xx` al recibir el mensaje y procésalo después. Así no se agota el tiempo del intento.
Reconocer mensajes repetidos	El mismo resultado puede llegar más de una vez. Usa el `transactionId` para no procesarlo dos veces.
Reconocer que somos nosotros	Al crear la consulta puedes mandar tus propios encabezados, por ejemplo un token. Los incluimos en la llamada a tu webhook para que la autentiques.

Entrega y cobro

Las reglas, sin letra chica.

Hasta 3 intentosDe inmediato, un minuto después y cinco minutos después. Un intento falla si tu dirección no contesta 2xx en 10 segundos. No seguimos redirecciones.

Se cobra cuando hay resultadoEl acuse no cuesta. Los créditos se cobran una sola vez, cuando la consulta se resuelve, y el campo billable te dice si ese resultado contó.

⚑

Tu dirección es tu responsabilidadEl resultado se cobra aunque tu webhook no lo haya podido recibir. Por eso conviene que esté siempre disponible.

Respaldo en semanas cotizadasEn ese servicio, si tu webhook falló, puedes consultar el resultado con el folio durante 24 horas, sin costo.

Para tu equipo técnico

Un receptor en diez líneas.

Esto es todo lo que necesita un webhook para funcionar bien: reconocer la llamada, contestar de inmediato, descartar repetidos y decidir con type.

Contesta primero, procesa despuésEl 2xx va antes que tu lógica de negocio.

Mismo formato de siempreEl cuerpo es el envelope estándar: status, type, message, data, transactionId y billable.

Los errores de captura se avisan al momentoUna petición inválida recibe INVALID_REQUEST en la misma llamada, no en el webhook, y no se cobra.

Ver la referencia técnica ↗

tu-webhook
          
          
        
app.post("/hooks/origoid", express.json(), (req, res) => {
  // 1. ¿viene de OrigoID? compara el token que tú enviaste
  if (req.get("authorization") !== `Bearer ${process.env.WEBHOOK_TOKEN}`)
    return res.sendStatus(401);

  res.sendStatus(200);                    // 2. contesta "recibido"

  const r = req.body;
  if (yaProcesado(r.transactionId)) return;  // 3. descarta repetidos
  procesar(r.type, r.data);               // 4. decide con type
});@app.post("/hooks/origoid")
def origoid_webhook():
    # 1. ¿viene de OrigoID? compara el token que tú enviaste
    if request.headers.get("Authorization") != f"Bearer {WEBHOOK_TOKEN}":
        return "", 401

    r = request.get_json()
    if not ya_procesado(r["transactionId"]):   # 3. descarta repetidos
        encolar(r["type"], r["data"])          # 4. decide con type

    return "", 200                           # 2. contesta "recibido"Lo que llega a tu webhook
{
  "status": "OK",
  "type": "SUCCESS",
  "message": "NSS found",
  "data": { "nss": "00000000000" },
  "transactionId": "39b972d3-20a8-539a-acfb-70657588df9b",
  "billable": true
}

Preguntas frecuentes

Lo que suelen preguntarnos.

¿Qué es un webhook?

Una dirección de tu sistema que recibe mensajes. En lugar de que tú preguntes una y otra vez si ya está el resultado, nosotros te lo enviamos a esa dirección en cuanto está listo.

¿Necesito un servidor propio?

Necesitas una dirección https pública que reciba el mensaje. Puede ser un servidor tuyo, una función en la nube o un servicio de tu plataforma: cualquier cosa que acepte una petición y conteste "recibido".

¿Cómo sé que el mensaje viene de OrigoID?

Al crear la consulta puedes incluir tus propios encabezados, por ejemplo un token secreto. Los mandamos de vuelta en la llamada a tu webhook y tú verificas que coincidan.

¿Qué pasa si mi dirección está caída?

Lo intentamos tres veces: de inmediato, al minuto y a los cinco minutos. Si las tres fallan, el resultado ya no se reenvía. En semanas cotizadas puedes consultarlo con el folio durante 24 horas.

¿Me cobran si mi webhook no recibió el resultado?

Sí. El crédito se cobra cuando la consulta se resuelve, la reciba o no tu dirección, porque la consulta sí se realizó. El acuse inicial nunca se cobra.

¿Puedo recibir el mismo resultado dos veces?

Puede pasar. Por eso conviene guardar el folio, el transactionId, y descartar los mensajes que ya procesaste.