Replay a message

POST

/v1/messages/{id}/replay

curl --request POST \
  --url https://api.hookbridge.io/v1/messages/01935abc-def0-7123-4567-890abcdef012/replay \
  --header 'Authorization: Bearer <token>'

• Production

Re-enqueue a message for delivery. This creates a new delivery attempt using the original payload. Useful for recovering from transient failures, testing endpoints, or re-processing a successfully delivered message.

Both failed and succeeded messages can be replayed, as long as the payload is still within its retention window. Retention is anchored to the message’s creation time (created_at; received_at for inbound messages) regardless of status, so replaying does not extend the retention window.

Limits: Maximum 10 replays per message.

Authorizations

• BearerAuth

Parameters

Path Parameters

id

required

string format: uuid

Unique message identifier (UUIDv7)

Example

01935abc-def0-7123-4567-890abcdef012

Responses

200

Message successfully re-enqueued

Media typeapplication/json

object

message

string

data

object

message_id

string

status

string

Allowed values: queued

meta

object

request_id

Unique identifier for this request (useful for support)

string

Example

{
  "message": "Message queued for replay",
  "data": {
    "message_id": "01935abc-def0-7123-4567-890abcdef012",
    "status": "queued"
  },
  "meta": {
    "request_id": "req_xyz123"
  }
}

401

Unauthorized - Invalid or missing API key

Media typeapplication/json

object

error

object

code

Machine-readable error code

string

message

Human-readable error message

string

meta

object

request_id

Unique identifier for this request (useful for support)

string

Example

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  },
  "meta": {
    "request_id": "req_xyz123"
  }
}

404

Resource not found

Media typeapplication/json

object

error

object

code

Machine-readable error code

string

message

Human-readable error message

string

meta

object

request_id

Unique identifier for this request (useful for support)

string

Example

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Message not found"
  },
  "meta": {
    "request_id": "req_xyz123"
  }
}

409

Message cannot be replayed due to its current state. Possible error codes: DELIVERY_IN_PROGRESS (message is currently being delivered), RETRY_IN_PROGRESS (message is in active fast retry after a 429 response).

Media typeapplication/json

object

error

object

code

Machine-readable error code

string

message

Human-readable error message

string

meta

object

request_id

Unique identifier for this request (useful for support)

string

Examples

Fast retry in progress

{
  "error": {
    "code": "RETRY_IN_PROGRESS",
    "message": "Message is in active fast retry; wait for retries to complete or fail before replaying"
  },
  "meta": {
    "request_id": "req_xyz123"
  }
}

Delivery in progress

{
  "error": {
    "code": "DELIVERY_IN_PROGRESS",
    "message": "Message is currently being delivered; wait for delivery to complete before replaying"
  },
  "meta": {
    "request_id": "req_xyz123"
  }
}

410

Message payload is no longer available for replay. Possible error codes: RETENTION_EXPIRED (the message’s retention window has elapsed), PAYLOAD_UNAVAILABLE (the payload was cleaned up by the sweeper before retention expired), MESSAGE_DELETED (the message was explicitly deleted).

Media typeapplication/json

object

error

object

code

Machine-readable error code

string

message

Human-readable error message

string

meta

object

request_id

Unique identifier for this request (useful for support)

string

Examples

Retention window elapsed

{
  "error": {
    "code": "RETENTION_EXPIRED",
    "message": "Message retention period has expired and payload is no longer available for replay"
  },
  "meta": {
    "request_id": "req_xyz123"
  }
}

Payload already cleaned up

{
  "error": {
    "code": "PAYLOAD_UNAVAILABLE",
    "message": "Message payload has already been cleaned up and cannot be replayed"
  },
  "meta": {
    "request_id": "req_xyz123"
  }
}

Message explicitly deleted

{
  "error": {
    "code": "MESSAGE_DELETED",
    "message": "Message has been deleted and cannot be replayed"
  },
  "meta": {
    "request_id": "req_xyz123"
  }
}

429

Replay limit exceeded

Media typeapplication/json

object

error

object

code

Machine-readable error code

string

message

Human-readable error message

string

meta

object

request_id

Unique identifier for this request (useful for support)

string

Example

{
  "error": {
    "code": "REPLAY_LIMIT_EXCEEDED",
    "message": "Message has already been replayed 10 times (limit: 10)"
  },
  "meta": {
    "request_id": "req_xyz123"
  }
}