Skip to content

API Reference

This reference documents the public data-plane APIs for ingesting and consuming messages.

Base URL: https://app.hooque.io

Authentication

Role Method Header / Parameter
Producer (Ingest) Shared Secret (Optional) Query: ?token=... or Header: X-Webhook-Token: ...
Consumer (Pull/SSE) Queue ID + Token Header: Authorization: Bearer <TOKEN>

Ingest

Send a Message

Publish a new message to the webhook queue.

POST /hooks/{webhookId}

Headers - Content-Type: Any (e.g., application/json, application/xml)

Query Parameters - token: (Optional) The secret token if configured for the webhook.

Body - The raw payload from the producer.

Response - 202 Accepted 

{
  "received": true,
  "id": "msg_..."
}

Consume

The consume API allows you to pull messages from your queue.

Base URL: https://app.hooque.io/queues/{queueId}

Pull Message

Retrieve the next available message from the queue.

GET /queues/{queueId}/next

Query Parameters - autoAck: boolean (Default: false). If true, the message is acknowledged immediately upon delivery.

Response - 200 OK: A message is available. The body is the raw payload. - 204 No Content: The queue is empty.

Response Headers - X-Hooque-Meta: JSON object containing delivery metadata and action URLs. - Link: RFC 5988 links for ack, nack, and reject.

Example X-Hooque-Meta 

{
  "messageId": "msg_123",
  "deliveryId": "del_456",
  "attempts": 1,
  "ackUrl": "https://app.hooque.io/queues/cons_1/ack/del_456?...",
  "nackUrl": "https://app.hooque.io/queues/cons_1/nack/del_456?...",
  "rejectUrl": "https://app.hooque.io/queues/cons_1/reject/del_456?..."
}

Stream Messages (SSE)

Listen for messages in real-time.

GET /queues/{queueId}/stream

Query Parameters - autoAck: boolean (Default: false).

Response - Content-Type: text/event-stream

Events - message: Sent when a new message is available. - keep-alive: Sent periodically to keep the connection open.

Event Data 

{
  "payload": { ... }, // The JSON payload (or string if not JSON)
  "meta": {
    "messageId": "msg_...",
    "deliveryId": "del_...",
    "ackUrl": "..."
  }
}

Acknowledge

Perform actions on a delivered message. You should use the full URLs provided in the Link or X-Hooque-Meta headers of the delivery response.

Ack (Success)

Mark the message as successfully processed.

POST /queues/{queueId}/ack/{deliveryId}

Nack (Retry)

Return the message to the queue for redelivery.

POST /queues/{queueId}/nack/{deliveryId}

Body (Optional) 

{
  "reason": "Database connection failed"
}

Reject (Dead Letter)

Permanently remove the message from the queue (e.g., invalid format).

POST /queues/{queueId}/reject/{deliveryId}

Body (Optional) 

{
  "reason": "Invalid payload signature"
}