Async Hooks

Async hooks let your endpoint return HTTP 202 to acknowledge receipt, then call back to Posthook when processing completes. This removes the 10-second delivery timeout for long-running tasks like video processing, report generation, or third-party API calls.

Async hooks is in beta. Enable it per-project in Project Settings.

Delivery Flow

When async hooks are enabled, each delivery includes two extra headers: Posthook-Ack-URL and Posthook-Nack-URL.

Your endpoint receives the delivery and returns 202 Accepted.
Your code processes the work.
You call back with the result.

Callback	Result
POST to ack URL	Hook marked completed
POST to nack URL	Hook retried or failed per your retry policy
Neither (deadline passes)	Hook retried or failed per your retry policy

Receiving Async Deliveries

Return 202 immediately, then process in the background and call ack() or nack() when done.

import express from 'express';
import { Signatures, SignatureVerificationError } from '@posthook/node';

const app = express();
const signatures = new Signatures(process.env.POSTHOOK_SIGNING_KEY);

app.post('/webhooks/process-video', express.raw({ type: '*/*' }), async (req, res) => {
  try {
    const delivery = signatures.parseDelivery(req.body, req.headers);

    res.status(202).end();
    try {
      await processVideo(delivery.data.videoId);
      await delivery.ack();
    } catch (err) {
      await delivery.nack({ error: err.message });
    }
  } catch (err) {
    if (err instanceof SignatureVerificationError) {
      return res.status(401).json({ error: err.message });
    }
    throw err;
  }
});

import os
from fastapi import FastAPI, Request, BackgroundTasks, HTTPException
from fastapi.responses import Response
import posthook

app = FastAPI()
client = posthook.Posthook(os.environ["POSTHOOK_API_KEY"], signing_key=os.environ["POSTHOOK_SIGNING_KEY"])

async def process_and_ack(delivery):
    try:
        await process_video(delivery.data["video_id"])
        await posthook.async_ack(delivery.ack_url)
    except Exception as e:
        await posthook.async_nack(delivery.nack_url, {"error": str(e)})

@app.post('/webhooks/process-video')
async def handle_webhook(request: Request, background_tasks: BackgroundTasks):
    body = await request.body()
    headers = dict(request.headers)

    try:
        delivery = client.signatures.parse_delivery(body, headers)
    except posthook.SignatureVerificationError:
        raise HTTPException(status_code=401)

    background_tasks.add_task(process_and_ack, delivery)
    return Response(status_code=202)

package main

import (
	"context"
	"io"
	"net/http"
	"os"

	posthook "github.com/posthook/posthook-go"
)

var client, _ = posthook.NewClient(os.Getenv("POSTHOOK_API_KEY"), posthook.WithSigningKey(os.Getenv("POSTHOOK_SIGNING_KEY")))

func handleWebhook(w http.ResponseWriter, r *http.Request) {
	body, _ := io.ReadAll(r.Body)

	delivery, err := client.Signatures.ParseDelivery(body, r.Header)
	if err != nil {
		http.Error(w, "Invalid signature", http.StatusUnauthorized)
		return
	}

	w.WriteHeader(http.StatusAccepted)
	go func() {
		if err := processVideo(delivery.Data); err != nil {
			delivery.Nack(context.Background(), map[string]any{"error": err.Error()})
			return
		}
		delivery.Ack(context.Background(), nil)
	}()
}

Make sure async hooks is enabled in Project Settings. Without the callback headers, long-running work will hit the standard 10-second delivery timeout.

Developing locally? Async hooks work with the CLI in forward mode — the callback headers are forwarded automatically.

Passing Work to a Queue

If processing happens in a separate worker or service, pass the raw callback URLs through your queue and call them from the worker.

// Webhook handler — enqueue and respond
app.post('/webhooks/process-video', express.raw({ type: '*/*' }), async (req, res) => {
  const delivery = signatures.parseDelivery(req.body, req.headers);

  await videoQueue.add('transcode', {
    videoId: delivery.data.videoId,
    ackUrl: delivery.ackUrl,
    nackUrl: delivery.nackUrl,
  });
  return res.status(202).end();
});

// Worker — process and call back
videoQueue.process('transcode', async (job) => {
  try {
    await processVideo(job.data.videoId);
    await fetch(job.data.ackUrl, { method: 'POST' });
  } catch (err) {
    await fetch(job.data.nackUrl, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ error: err.message }),
    });
  }
});

Callback URLs are plain HTTPS endpoints. Any service that can make an HTTP POST can call them — no SDK required.

Timeouts

If neither ack nor nack is received before the deadline, the attempt is treated as a failure and follows your retry settings. The default timeout is 300 seconds (5 minutes). Override it per delivery by setting a Posthook-Async-Timeout header on your 202 response:

res.setHeader('Posthook-Async-Timeout', '600'); // 10 minutes
res.status(202).end();

	Value
Minimum	`10` seconds
Default	`300` seconds (5 min)
Maximum	`10800` seconds (3 hours)

Posthook-Async-Timeout is a response header that you set. This is the opposite direction from the other Posthook-* headers, which Posthook sends to you.

Callback Responses

When you POST to an ack or nack URL, Posthook returns a status code indicating what happened.

Status	Meaning	Action
`200`	Callback accepted, or hook already resolved for this attempt	None
`401`	Invalid callback token	Check configuration
`404`	Hook was deleted	None
`409`	Hook already moved to a newer attempt	None
`410`	Callback expired (token or deadline elapsed)	None — treat as terminal

200 can mean your callback was applied, or the attempt was already resolved moments earlier (e.g., timeout won the race). Both are terminal for that callback. 409 means the hook has already advanced to a newer retry attempt — your callback URL belongs to an older attempt. No action needed; Posthook is handling the newer attempt. 410 means the callback URL can no longer affect hook state. The token expired or the async deadline elapsed. Treat it as terminal.

SDK behavior

The SDK ack() and nack() helpers handle these responses for you:

200, 404, 409 resolve without throwing. 200 includes an applied flag indicating whether state actually changed.
401 and 410 raise a callback error.

Nack bodies

Ack request bodies are ignored. Nack request bodies are captured for diagnostics (up to 8 KB). Include structured JSON if you want failure details visible in the dashboard.

await delivery.nack({
  error: 'Transcoding failed',
  code: 'FFMPEG_EXIT_1',
  duration_ms: 45200,
});

Retries

Async failures — both nack and timeout — use the same retry logic as synchronous failures. A nack or timeout increments the attempt counter and applies your project’s retry policy (or the hook’s retryOverride). If the hook has exhausted all retries, it is marked as failed. There’s nothing new to configure. If your project retries 5 times with exponential backoff, that same policy applies whether the failure came from an HTTP 500, a nack, or a timeout.

Async hooks still follow at-least-once delivery. Keep your handlers idempotent.

Monitoring

The hook detail page in the dashboard shows async-specific state:

Awaiting Ack status while a callback is pending
Ack deadline for the current attempt
Outcome per attempt: ack, nack, or timeout
Elapsed time between delivery and callback
Captured nack body (up to 8 KB)

Getting Started

Core Concepts

Features

Patterns

Reference

Updates

Delivery Flow

Receiving Async Deliveries

Passing Work to a Queue

Timeouts

Callback Responses

SDK behavior

Nack bodies

Retries

Monitoring

​Delivery Flow

​Receiving Async Deliveries

​Passing Work to a Queue

​Timeouts

​Callback Responses

​SDK behavior

​Nack bodies

​Retries

​Monitoring

Delivery Flow

Receiving Async Deliveries

Passing Work to a Queue

Timeouts

Callback Responses

SDK behavior

Nack bodies

Retries

Monitoring