API — Heartbeat (Push)

O endpoint de Heartbeat recebe pings dos seus serviços. Diferente dos outros endpoints da API, ele não requer autenticação — a autenticação é feita pelo token único da URL.

POST /push/:token

Registra um ping de heartbeat para o monitor correspondente.

Não requer autenticação por header. O token na URL identifica e autentica o monitor.

curl -X POST https://api.thealert.io/push/SEU-TOKEN-AQUI

Resposta (200 OK):

{ "ok": true }

Onde obter o token

O token é gerado automaticamente ao criar um monitor do tipo Heartbeat (Push):

TheAlert → Novo Monitor → Tipo: Heartbeat (Push)
Configure nome e intervalo esperado
Salve — a URL de push é exibida na página do monitor:

https://api.thealert.io/push/abc123def456-seu-token-unico

⚠️

Mantenha o token privado. Qualquer pessoa com a URL pode enviar pings para o seu monitor. Se o token for comprometido, delete o monitor e crie um novo.

Rate limit

O endpoint aceita no máximo 10 requisições por minuto por token. Para crons que rodam com frequência menor que 6 segundos, considere se o Heartbeat é o tipo correto — ou implemente debounce no lado do cliente.

Requisições	Status
≤ 10/min	`200 OK`
> 10/min	`429 Too Many Requests`

Lógica de detecção de falha

Após receber um ping, o TheAlert aguarda o próximo ping dentro do intervalo de interval × 1.5 segundos.

Monitor com intervalo de 60 segundos: aguarda até 90 segundos pelo próximo ping
Monitor com intervalo de 5 minutos: aguarda até 7,5 minutos
Monitor com intervalo de 1 hora: aguarda até 1,5 horas

Se nenhum ping chegar dentro desse período → monitor vai para DOWN e alertas são disparados.

Exemplos de integração

cURL simples

curl -s -X POST https://api.thealert.io/push/SEU-TOKEN

Cron Linux — ping a cada minuto

# Adicione ao crontab: crontab -e
* * * * * curl -s -X POST https://api.thealert.io/push/SEU-TOKEN

Cron com condição — só pinga em caso de sucesso

#!/bin/bash
# /scripts/backup-diario.sh
 
pg_dump producao > /backups/db-$(date +%Y%m%d).sql.gz
 
if [ $? -eq 0 ]; then
    curl -s -X POST https://api.thealert.io/push/SEU-TOKEN
fi

Node.js — worker periódico

const HEARTBEAT_URL = 'https://api.thealert.io/push/SEU-TOKEN'
 
async function runWorker() {
  try {
    await processQueue()
    // Confirma execução bem-sucedida
    await fetch(HEARTBEAT_URL, { method: 'POST' })
  } catch (err) {
    console.error('Worker falhou:', err)
    // Não envia ping — TheAlert detecta ausência
  }
}
 
setInterval(runWorker, 60_000)

Python — script periódico

import requests
import time
 
HEARTBEAT_URL = 'https://api.thealert.io/push/SEU-TOKEN'
 
def run_job():
    # Seu processamento aqui
    process_data()
 
while True:
    try:
        run_job()
        requests.post(HEARTBEAT_URL, timeout=5)
    except Exception as e:
        print(f'Job falhou: {e}')
        # Não envia ping
 
    time.sleep(60)

PHP — script agendado

<?php
try {
    runMyScheduledTask();
 
    // Notifica TheAlert de sucesso
    file_get_contents(
        'https://api.thealert.io/push/SEU-TOKEN',
        false,
        stream_context_create(['http' => ['method' => 'POST']])
    );
} catch (Exception $e) {
    error_log('Task failed: ' . $e->getMessage());
    // Não envia ping
}

GitHub Actions — job agendado

name: Daily Backup
 
on:
  schedule:
    - cron: '0 3 * * *'  # Todo dia às 3h UTC
 
jobs:
  backup:
    runs-on: ubuntu-latest
    steps:
      - name: Executar backup
        run: ./scripts/backup.sh
 
      - name: Notificar TheAlert (sucesso)
        if: success()
        run: |
          curl -s -X POST ${{ secrets.THEALERT_HEARTBEAT_URL }}

Verificando a resposta

O endpoint retorna sempre {"ok": true} com status 200. Você pode verificar isso para confirmar que o ping foi recebido:

RESPONSE=$(curl -s -w "\n%{http_code}" -X POST https://api.thealert.io/push/SEU-TOKEN)
HTTP_CODE=$(echo "$RESPONSE" | tail -1)
 
if [ "$HTTP_CODE" != "200" ]; then
    echo "AVISO: Ping do TheAlert falhou (HTTP $HTTP_CODE)"
fi

Diferença entre Heartbeat e outros monitores

Aspecto	HTTP/TCP/DNS	Heartbeat
Quem inicia a checagem	TheAlert	Seu serviço
Requer acesso externo	Sim	Não
Ideal para	Sites, APIs, servidores	Crons, workers, jobs
Autenticação	Via API Key	Via token na URL

Próximos passos

Status Pages Service Map