Webhooks: avisa a otras herramientas de lo que pasó

#Qué es un webhook

Piensa en ello como tu proyecto llamando a otro servicio para contarle lo que acaba de pasar. Le das a Briks una dirección (una URL que te dio la otra herramienta), eliges los eventos que debe comunicar y, cada vez que ocurre uno, Briks envía un mensaje allí. Muchas herramientas de automatización, de listas de clientes y complementos de hojas de cálculo pueden darte una dirección así.

Técnicamente, cada mensaje es una solicitud POST: una llamada que lleva un cuerpo, escrito aquí en JSON, un formato de texto plano que leen los programas. La herramienta receptora lee el cuerpo y hace lo que hayas configurado.

record.changed sigue los cambios hechos en el estudio: un registro añadido, editado o eliminado en la pestaña Database, una colección vaciada o la base de datos restaurada. Los registros que el sitio publicado guarda por sí mismo, como una solicitud de reserva que envía un visitante, no lo activan.

form.received se envía tanto para los envíos desde la vista previa como desde producción. Cada mensaje indica de cuál se trata, para que la otra herramienta pueda omitir los envíos de la vista previa.

#Límites de cada plan

Cuando se agotan las llamadas del día, un envío no se manda y se marca como Failed con este mensaje: Today's calls for this project are used up, so this delivery was not sent. Send it again tomorrow.

Cuando un proyecto tiene tantos webhooks como permite su plan, Add webhook aparece en gris y un enlace Get more junto al contador abre la ventana de mejora, que indica el plan más pequeño con sitio para otro.

#Añadir un webhook

Cada webhook de la lista muestra su dirección, su nota y sus eventos, con qué secreto está firmado (los primeros caracteres) y cómo fue la última entrega. Su interruptor lo pone en On o Off, y sus tres puntos contienen Send a test event (hasta diez por hora, solo mientras está activado), Change, New signing secret y Delete.

#Cómo es una entrega

Cada envío tiene las mismas tres partes: type (el código del evento), timestamp (cuándo ocurrió, en UTC) y data (los detalles). Aquí tienes una entrada de formulario:

Cada envío incluye además tres cabeceras: webhook-id (el id del mensaje), webhook-timestamp (cuándo se envió, en segundos) y webhook-signature. Siguen el formato abierto Standard Webhooks, así que las herramientas que lo entienden pueden comprobar los envíos por ti.

#Comprueba que un envío es genuino

Cualquiera puede enviar un mensaje a una dirección, así que quien lo recibe debe comprobar la firma antes de fiarse. La firma se hace con el secreto de firma que solo tienen tú y Briks. Cuando un proyecto tiene un webhook, la página Webhooks muestra un breve ejemplo de código bajo Checking a delivery is genuine. En palabras, la comprobación es así:

1. Toma el cuerpo exactamente como llegó, como texto, antes de leerlo como JSON.
2. Une el webhook-id, el webhook-timestamp y el cuerpo con puntos entre ellos.
3. Toma tu secreto, quita el whsec_ del principio y decodifica el resto desde base64. Esa es la clave.
4. Firma el texto unido con HMAC SHA-256 y esa clave, escribe el resultado en base64 y antepón v1,.
5. La entrega es auténtica si coincide con uno de los valores separados por espacios de webhook-signature y la marca de tiempo está dentro de los cinco minutos previos o posteriores al momento actual.

Una entrega que se reintenta conserva su webhook-id, así que el receptor puede guardar los ids que ya procesó y omitir las repeticiones.

#Entregas y reintentos

Deliveries muestra todos los envíos de los últimos treinta días, del más reciente al más antiguo. Acótalos con Status y pulsa Show. Haz clic en uno para ver el mensaje completo, cualquier error y lo que respondió la dirección.

Cada intento espera hasta 15 segundos una respuesta. Si la respuesta no es un 2xx, Briks vuelve a intentarlo: cinco intentos en total, el primero de inmediato y los siguientes tras unos 30 segundos, 2 minutos, 8 minutos y 32 minutos, es decir, unos 45 minutos del primero al último. Una respuesta 410 (gone) detiene los reintentos al instante. Las redirecciones no se siguen, así que indica la dirección final.

Cuando una entrega está en Failed o Delivered, Send again envía el mismo mensaje con el mismo id, firmado de nuevo. El webhook tiene que estar activado.

#Información y ajustes

Insights resume los últimos treinta días: Deliveries, el porcentaje Delivered, Failed after every try (con el número de reintentos que hizo falta) y el tiempo de Average answer. Más abajo, By event y By address muestran dónde se concentran los fallos.

Settings tiene Download JSON en Download the webhooks, con la dirección, los eventos y la nota de cada webhook. Los secretos de firma nunca se incluyen. Su zona de peligro contiene Clear log, que elimina el registro de envíos y detiene cualquier reintento, y Delete all, que quita todos los webhooks después de escribir el nombre del proyecto. Ambos son para Owners y Admins.

#Ejemplo práctico: enviar las entradas de un formulario a otra herramienta

Las entradas de los formularios no se pueden exportar desde el estudio, así que un webhook es la forma de guardarlas en otra herramienta según llegan. El estudio también las conserva: las últimas 100 aparecen en Settings, Forms.