# The instant a job throws.

> Get a push when a background job or worker fails. Hook Pocket Alert into Sidekiq, Celery, Laravel queues, or BullMQ and worker failures hit your phone fast.

<!-- source: https://pocketalert.app/use-cases/background-job-alerts -->

Call Pocket Alert from your job's failure hook in Sidekiq, Celery, Laravel, or BullMQ. A thrown worker carries its job name, arguments, and exception to your phone, and a completion ping lands when critical jobs finish.

## Three steps to background job alerts

1. **Get the API key or CLI** — Create an API key, or install the Pocket Alert CLI for shell-based workers.
2. **Hook into failures** — Call Pocket Alert from your queue framework's failure hook and pass the job name and error.
3. **Catch dead workers** — Trigger a failing job. Your phone buzzes with which worker died and why.

## Never miss a dead worker

A worker that dies quietly takes your jobs down with it. Get told when a task throws.

- **Hooks into any queue** — Sidekiq, Celery, Laravel, BullMQ, and Hangfire call Pocket Alert from a failure hook you already have.
- **Alert on failure** — Wire it into the death handler and only failed jobs reach you.
- **Full failure context** — Job class, arguments, and exception arrive in the message, so you can triage without opening your tracker.
- **Confirm it ran** — Ping on completion for critical jobs. A silent nightly import means it stopped running.
- **A channel per worker** — Give each worker its own application so a stuck queue lands in a channel you can spot at a glance.
- **Instant on throw** — A thrown worker pushes to your phone well before you would think to tail the logs.

## Alert straight from your job handler

### Laravel queue — the failed() hook

```
public function failed(Throwable $e): void
{
    Http::withHeaders(['Token' => 'YOUR_API_KEY'])
        ->post('https://api.pocketalert.app/v1/messages', [
            'title' => 'Job failed: ' . class_basename($this),
            'message' => $e->getMessage(),
            'level' => 'critical',
        ]);
}
```

### Sidekiq — a death handler

In `config/initializers/sidekiq.rb`, fire once retries are exhausted:

```
Sidekiq.configure_server do |config|
  config.death_handlers << ->(job, ex) do
    Net::HTTP.post(
      URI('https://api.pocketalert.app/v1/messages'),
      { title: "Job died: #{job['class']}",
        message: "jid #{job['jid']}: #{ex.message}" }.to_json,
      'Token' => 'YOUR_API_KEY', 'Content-Type' => 'application/json')
  end
end
```

### Celery — the task_failure signal

```
import requests
from celery.signals import task_failure

@task_failure.connect
def notify_failure(sender=None, task_id=None, exception=None, **kw):
    requests.post(
        'https://api.pocketalert.app/v1/messages',
        headers={'Token': 'YOUR_API_KEY'},
        json={'title': f'Task failed: {sender.name}',
              'message': f'{task_id}: {exception}'})
```

### BullMQ — the worker failed event

```
worker.on('failed', async (job, err) => {
  await fetch('https://api.pocketalert.app/v1/messages', {
    method: 'POST',
    headers: { 'Token': 'YOUR_API_KEY', 'Content-Type': 'application/json' },
    body: JSON.stringify({
      title: `Job failed: ${job?.name}`,
      message: `${job?.id}: ${err.message}`,
    }),
  });
});
```

The [docs](https://info.pocketalert.app/getting-started.html) cover targeting a specific application or device.

## FAQ

### How do I alert on failed background jobs?

Call the Pocket Alert API or CLI from your job's failure handler or rescue block. A thrown worker sends a push notification to your phone with the job name and the error attached.

### Can I hook into my queue framework?

Yes. Most queue frameworks expose a failure callback: Sidekiq death handlers, Celery task_failure, and Laravel failed(). Put the Pocket Alert call there and only genuine failures notify you.

### Can I include the job and error?

Put the job class, arguments, and exception message in the body. The alert tells you which job died and why, which usually saves a trip to your error tracker.

### Which queue systems are supported?

Sidekiq, Resque, Celery, RQ, Laravel queues, BullMQ, Hangfire, and Kubernetes Jobs all work through either a failure hook or a non-zero exit.

### Can I confirm a job actually ran?

Send a completion notification on critical jobs. If a nightly import never pings, the worker probably stopped processing without raising anything.

### Can a dead worker alert override Do Not Disturb?

Yes. Pass level=critical in the failure hook and Android routes the push through a channel that bypasses Do Not Disturb, while iPhone delivers it as a time-sensitive notification that breaks through Focus. Completion pings for routine jobs can use level=silent and stay in history without a sound.