Webhook

Una solicitud HTTP POST que una plataforma envía a tu servidor cuando algo cambia, para que tu sistema se entere del evento sin consultar una y otra vez (polling).

#Cómo funciona en CryptoLike

CryptoLike envía un evento JSON firmado a tu endpoint cada vez que un pago, un depósito o un retiro cambia de estado. Hay 21 tipos de eventos, como invoice.paid, invoice.underpaid, invoice.expired, deposit.confirmed y withdrawal.completed. Agrega un endpoint en el panel (Desarrolladores → Webhooks → Agregar endpoint) o con POST /v1/webhooks/endpoints: una URL https:// en un host público, los tipos de eventos o *, y un secreto.

Cada solicitud lleva X-Event-Id, X-Event-Type, X-Timestamp y X-Signature; el cuerpo tiene event_id, type, created_at y data. Responde con un estado 2xx en menos de 10 segundos. Si no, la entrega se reintenta después de 1 min, 5 min, 15 min, 1 h, 6 h y 24 h (7 intentos, unas 31 horas) y luego se marca como agotada; reenvíala desde Desarrolladores → Webhooks → Entregas → Reintentar.

La entrega es «al menos una vez», así que el mismo evento puede llegar dos veces con el mismo event_id: guárdalo y omite las repeticiones. Los eventos de un mismo pago pueden llegar desordenados; usa created_at y el status dentro de data. «Enviar evento de prueba» en el panel envía un ping firmado a un endpoint. Verifica cada solicitud; consulta firma del webhook.

#Ejemplo

Así se ve una solicitud de webhook de CryptoLike. El cuerpo aparece formateado para leerlo; los bytes que recibes pueden tener otro orden de claves y otros espacios. Interprétalo como JSON y verifica la firma sobre los bytes crudos, tal como llegaron:

POST /your/path HTTP/1.1
Content-Type: application/json
X-Event-Id: 6f1c2c1e-3b2a-4d5e-8f90-1234567890ab
X-Event-Type: invoice.paid
X-Timestamp: 1700000000
X-Signature: sha256=788e60a2141669b4c7616c1c616fefb8ec38df0948fba19c6f4e48c616e46c21

{"event_id":"6f1c2c1e-3b2a-4d5e-8f90-1234567890ab","type":"invoice.paid","created_at":"2023-11-14T22:13:20Z","data":{"invoice":{"id":"0e8c9a4b-1111-4222-8333-444455556666","status":"paid"}}}