Webhooks y registro de entregas
Reenvía eventos, con firmas y reintentos.
El webhook notifica a tu sistema externo en tiempo real sobre stmpr eventos, como un nuevo invitado, sello, estado de recompensa o canje.
Cada solicitud está firmada para que el sistema receptor pueda verificar que efectivamente fue enviada por el stmpr. Si la entrega falla, el sistema retrasa el intento de nuevo.
El registro de entrega muestra el evento, la hora, el código de respuesta y los resultados de los intentos.
https://stmpr.io/dashboard/developers · Webhooks
Paso a paso
- Ve a la página de Webhooks en el menú de Integraciones.
- Añade un endpoint HTTPS y selecciona los eventos que quieres reenviar.
- Guarda el secreto de firma en la configuración segura del sistema anfitrión.
- Envía un evento de prueba y verifica la firma, el cuerpo de la solicitud y la respuesta 2xx exitosa.
- Después de la puesta en directo, monitoriza el registro de entregas. En el punto final fijo, reinicia la no entrega.
Qué contiene una petición de webhook
- Cuerpo de la petición: el nombre del evento (event), la marca de tiempo created_at y el objeto data.
- data.wallet: el identificador y el nombre de la tarjeta de fidelidad.
- data.customer: el identificador del cliente, su código de cuatro dígitos, los sellos acumulados, los sellos necesarios, si la recompensa está lista, y las fechas de alta y de última actividad.
- customer.created: un cliente se ha dado de alta, sin campo adicional.
- stamp.added: lo anterior más el origen del sello (manual, api, auto, survey_reward, kiosk).
- stamp.removed: igual que al añadir, con el origen de la retirada.
- reward.ready: el cliente ha reunido los sellos que pide la recompensa, sin campo adicional.
- reward.redeemed: el tipo de canje (staff, manual, auto, api).
- pass.updated: qué tarjetas se han actualizado en el teléfono (apple, google).
- Cabeceras: X-Stmpr-Event lleva el nombre del evento, X-Stmpr-Delivery el identificador del envío y X-Stmpr-Signature es t=marca de tiempo,v1=HMAC-SHA256 firmado con tu secreto.
- Respuesta: esperamos un 2xx en 10 segundos. Si no llega, reintentamos cinco veces en total, con 10 segundos, 1 minuto, 5 minutos y 15 minutos de espera.
Petición de ejemplo por evento
customer.created
{
"event": "customer.created",
"created_at": "2026-09-01T14:12:03+00:00",
"data": {
"wallet": {
"id": "w_8Kd2Qm",
"name": "Kávé hűségkártya"
},
"customer": {
"id": "c_9YbVt3xQ",
"display_code": "4693",
"stamps_count": 0,
"stamps_required": 10,
"ready_to_redeem": false,
"created_at": "2026-07-14T09:20:11+00:00",
"last_activity_at": "2026-09-01T14:12:03+00:00"
}
}
}stamp.added
{
"event": "stamp.added",
"created_at": "2026-09-01T14:12:03+00:00",
"data": {
"wallet": {
"id": "w_8Kd2Qm",
"name": "Kávé hűségkártya"
},
"customer": {
"id": "c_9YbVt3xQ",
"display_code": "4693",
"stamps_count": 7,
"stamps_required": 10,
"ready_to_redeem": false,
"created_at": "2026-07-14T09:20:11+00:00",
"last_activity_at": "2026-09-01T14:12:03+00:00"
},
"source": "manual"
}
}stamp.removed
{
"event": "stamp.removed",
"created_at": "2026-09-01T14:12:03+00:00",
"data": {
"wallet": {
"id": "w_8Kd2Qm",
"name": "Kávé hűségkártya"
},
"customer": {
"id": "c_9YbVt3xQ",
"display_code": "4693",
"stamps_count": 6,
"stamps_required": 10,
"ready_to_redeem": false,
"created_at": "2026-07-14T09:20:11+00:00",
"last_activity_at": "2026-09-01T14:12:03+00:00"
},
"source": "manual"
}
}reward.ready
{
"event": "reward.ready",
"created_at": "2026-09-01T14:12:03+00:00",
"data": {
"wallet": {
"id": "w_8Kd2Qm",
"name": "Kávé hűségkártya"
},
"customer": {
"id": "c_9YbVt3xQ",
"display_code": "4693",
"stamps_count": 10,
"stamps_required": 10,
"ready_to_redeem": true,
"created_at": "2026-07-14T09:20:11+00:00",
"last_activity_at": "2026-09-01T14:12:03+00:00"
}
}
}reward.redeemed
{
"event": "reward.redeemed",
"created_at": "2026-09-01T14:12:03+00:00",
"data": {
"wallet": {
"id": "w_8Kd2Qm",
"name": "Kávé hűségkártya"
},
"customer": {
"id": "c_9YbVt3xQ",
"display_code": "4693",
"stamps_count": 0,
"stamps_required": 10,
"ready_to_redeem": false,
"created_at": "2026-07-14T09:20:11+00:00",
"last_activity_at": "2026-09-01T14:12:03+00:00"
},
"type": "staff"
}
}pass.updated
{
"event": "pass.updated",
"created_at": "2026-09-01T14:12:03+00:00",
"data": {
"wallet": {
"id": "w_8Kd2Qm",
"name": "Kávé hűségkártya"
},
"customer": {
"id": "c_9YbVt3xQ",
"display_code": "4693",
"stamps_count": 7,
"stamps_required": 10,
"ready_to_redeem": false,
"created_at": "2026-07-14T09:20:11+00:00",
"last_activity_at": "2026-09-01T14:12:03+00:00"
},
"passes": [
"apple",
"google"
]
}
}