Integración por eventos (Webhooks)

---

Propósito

TRAK pone a su disposición un único punto de conexión al que puede enviar eventos para mantener sincronizados sus pacientes con la plataforma: dar de alta un paciente o desactivarlo.

Cada petición indica el tipo de evento en el cuerpo, y TRAK ejecuta la acción correspondiente.

Nota: Para obtener sus credenciales de integración (identificador y clave), contacte con soporte@trak.es o con su persona de contacto en TRAK.

---

Cómo enviar un evento

Punto de conexión

Entorno	URL
Staging	https://stg.trakphysioapi.com/events/submit_event/
Producción	https://trakphysioapi.com/events/submit_event/

• Método: POST
• Content-Type: application/json

Cabeceras

Cabecera	Obligatoria	Descripción
X-Integration-Id	Sí	Su identificador de integración, proporcionado por TRAK.
Content-Type	Sí	application/json.
Signature	Sí	Firma del cuerpo para verificar la autenticidad (ver más abajo).

Firma de la petición

Para garantizar que la petición proviene de usted, cada llamada debe incluir la cabecera Signature con una firma HMAC-SHA256 del cuerpo, generada con la clave compartida que le entrega TRAK.

La firma se calcula sobre el cuerpo JSON serializado sin espacios (separadores , y :):

import hmac, hashlib, json

data_json = json.dumps(payload, separators=(",", ":"))   # sin espacios
signature = hmac.new(
    key=SHARED_SECRET.encode("utf-8"),
    msg=data_json.encode("utf-8"),
    digestmod=hashlib.sha256,
).hexdigest()
# -> enviar en la cabecera "Signature"

Importante: el cuerpo debe enviarse exactamente igual que se firmó. Cualquier diferencia (espacios o cambio en el orden de las claves) invalidará la firma.

---

Eventos

Alta de paciente

Da de alta el paciente en TRAK. Si el paciente ya existía (mismo user_id), se reactiva.

Cuerpo:

{
  "event": "patientPrescribedApp",
  "user_id": "123",
  "patient": {
    "name": "John Doe",
    "email": "johndoe@gmail.com"
  }
}

Campo	Obligatorio	Descripción
event	Sí	Debe ser patientPrescribedApp.
user_id	Sí	Identificador del paciente en su sistema.
patient.name	Sí	Nombre del paciente.
patient.email	Sí	Email del paciente.

Baja de paciente

Desactiva el paciente en TRAK.

Cuerpo:

{
  "event": "patientUnprescribedApp",
  "user_id": "123"
}

Campo	Obligatorio	Descripción
event	Sí	Debe ser patientUnprescribedApp.
user_id	Sí	Identificador del paciente en su sistema.

---

Respuestas

Código	Significado
200	Evento procesado correctamente.
400	Faltan datos obligatorios o la petición no es válida.
401	Firma inválida.
503	El evento indicado no está soportado.

// 200 OK
{ "message": "Event processed successfully." }

---

Ejemplos con curl

Los ejemplos usan el host de staging. En producción, sustituya stg.trakphysioapi.com por trakphysioapi.com.

# Alta de paciente
curl -X POST https://stg.trakphysioapi.com/events/submit_event/ \
  -H "Content-Type: application/json" \
  -H "X-Integration-Id: <su_identificador>" \
  -H "Signature: <firma_del_cuerpo>" \
  -d '{"event":"patientPrescribedApp","user_id":"123","patient":{"name":"John Doe","email":"johndoe@gmail.com"}}'

# Baja de paciente
curl -X POST https://stg.trakphysioapi.com/events/submit_event/ \
  -H "Content-Type: application/json" \
  -H "X-Integration-Id: <su_identificador>" \
  -H "Signature: <firma_del_cuerpo>" \
  -d '{"event":"patientUnprescribedApp","user_id":"123"}'