Documentación

Webhooks

Los webhooks te permiten integrar URBEM con tu aplicación al suscribirte a ciertos eventos. Cuando uno de los siguientes eventos ocurre, enviaremos un request HTTP POST a la URL configurada para el webhook. Puedes configurar múltiples webhooks para el mismo evento y éste recibirá un request por cada webhook.


Eventos

Al configurar un nuevo webhook puedes seleccionar un evento de los disponibles:

Nombre Descripción
Pagos creados Se dispara cada vez que un ciudadano realiza un pago (fallido, exitoso o pendiente) a cualquier servicio de tu organización.
Pagos exitosos Se dispara cada vez que un ciudadano realiza un pago exitoso a cualquier servicio de tu organización.
Pagos fallidos Se dispara cada vez que un ciudadano realiza un pago fallido a cualquier servicio de tu organización.
Documentos enviados Documentos enviados: Se dispara cada vez que un ciudadano envía documentos a cualquier servicio de tu organización como parte de un Caso ciudadano.
Documentos rechazados Documentos rechazados: Se dispara cada vez que una persona de tu organización revisa los documentos enviados por un ciudadano como parte de un caso ciudadano y rechaza alguno.
Documentos aprobados Documentos aprobados: Se dispara cada vez que una persona de tu organización revisa los documentos enviados por un ciudadano como parte de un caso ciudadano y aprueba todos.

Payloads

Cada tipo de evento tiene su propio formato de payload con la información relevante del mismo.

Para los eventos: pagos creados, pagos exitosos y pagos fallidos , el payload corresponde a un objeto payment. Ejemplo:

{
  "folio": "155-1F5D02",
  "name": "Luis Espinoza Ruiz",
  "email": "luis1@mail.com",
  "address": "Calle #333",
  "city": "Monterrey",
  "state": "Nuevo León",
  "zip_code": "25090",
  "amount": 70966,
  "citizen_case_id": 123,
  "procedure": "Licencia de conducir",
  "procedure_id": "licencia-111",
  "metadata": {
    "codigo_descuento": "XHF20"
  },
  "status": "failed",
  "description": "Pago para Licencia de Conducir",
  "created_at": "2019-01-24T15:06:50.575-06:00",
}

Para los eventos: documentos enviados, documentos rechazados y documentos aprobados , el payload corresponde a un objeto revision. Ejemplo:

{
  "id": 1,
  "citizen_case_id": 123,
  "action": "get_result",
  "comments": "Todo bien",
  "procedure": "Licencia de Conducir",
  "procedure_id": "licencia-111"
  "completed": true,
  "approved": false,
  "attachments_count": 1,
  "created_at": "2018-10-11T16:28:06.618-05:00",
  "updated_at": "2018-10-11T17:11:00.074-05:00",
  "assigned_to": "responsable@mail.com",
  "citizen_attachments": [
    {
      "id": 1,
      "status": "rejected",
      "rejected_reason": "mal formato",
      "requirement_name": "Identificación Oficial",
      "created_at": "2018-10-11T16:28:06.643-05:00",
      "attachment": {
        "id": 68,
        "url": "https://citizen_docs.url/identificacion.jpg",
        "filename": "identificación.jpg"
      }
    }
  ]
}

Estatus de un webhook

Cada webhook configurado tiene un estatus. Al inicio de la configuración de cualquier webhook este estatus será Pendiente. Una vez que se dispare el evento correspondiente al seleccionado para el webhook y se lleve a cabo el HTTP POST, tu aplicación deberá regresar un status 2xx para que el webhook pase de estatus Pendiente a estatus Válido. En caso de cualquier código de error como respuesta el webhook pasará a un estatus Inválido.


API Keys

URBEM autentica los requests de tu organización utilizando las API keys. Si no incluyes el API key como parámetro o utilizas un API key obsoleta o incorrecta en cualquier request que realices al URBEM API, ésta responderá con un error 401.

Cada organización cuenta con una API Key default con permisos de lectura y escritura. Si deseas agregar nuevas API keys con diferentes permisos puedes hacerlo desde la sección de Desarrolladores en el panel de configuración.

Ver documentación completa de URBEM API