Send a webhook

The /v1/send endpoint and every option you can set on a delivery.

Send an outbound HTTP request through Harepost. The request is queued and delivered to your target with automatic retries, and you get a queue_id back immediately.

POST https://api.harepost.com/v1/send
Authorization: Bearer hp_live_YOUR_KEY
Content-Type: application/json

The target must be on a domain your account has verified. Sending to an unverified domain returns 403. See domain verification.

Request body

Field	Type	Required	Notes
`target`	string	yes	The destination URL. Must be `https`. Cannot resolve to a private, loopback, or link-local address.
`method`	string	no	HTTP method for the delivery. One of `POST`, `PUT`, `PATCH`, `DELETE`, `GET`. Defaults to `POST`.
`headers`	object	no	Headers forwarded to your target. A few hop-by-hop and auth headers are stripped (see below).
`body`	string or object	no	The payload. A string is sent as-is. An object is JSON-encoded, and `Content-Type: application/json` is set if you did not provide one. Ignored for `GET`.
`delivery`	object	no	Retry and timeout policy. See the table below.
`idempotency_key`	string	no	Forwarded to your target as `X-Harepost-Idempotency-Key` so your endpoint can dedupe. Returned in the response.
`sign`	boolean	no	When `true`, the delivery is signed and carries an `X-Harepost-Signature` header your endpoint can verify. See verify signatures. Defaults to `false`.
`metadata`	object	no	Stored for your own reference and visible in the delivery history. Never sent to your target.

Delivery policy

All fields are optional and clamped to the ranges below.

Field	Type	Default	Range
`max_attempts`	number	`5`	`1` to `25`
`backoff`	string	`exponential`	`exponential` or `fixed`
`base_delay_ms`	number	`1000`	`100` to `60000`
`max_delay_ms`	number	`3600000`	`1000` to `43200000` (12 hours)
`jitter`	string	`full`	`full` or `none`
`timeout_ms`	number	`10000`	`1000` to `30000`
`respect_retry_after`	boolean	`true`	honors a `Retry-After` header from your target

A value outside its range is clamped to the nearest bound rather than rejected. How these interact during delivery is covered in retries and delivery behavior.

Headers Harepost adds

Every delivered request carries:

X-Harepost-Queue-Id — the delivery’s queue_id.
X-Harepost-Idempotency-Key — present only if you set one.
User-Agent: Harepost/1.0

These headers are stripped from anything you pass in headers, since Harepost or the network controls them: host, content-length, connection, transfer-encoding, keep-alive, upgrade, expect, and authorization.

Example

curl -X POST https://api.harepost.com/v1/send \
  -H "Authorization: Bearer hp_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target": "https://your-app.com/webhook",
    "body": { "event": "order.paid", "id": "ord_123" },
    "idempotency_key": "ord_123-paid",
    "delivery": { "max_attempts": 8, "base_delay_ms": 2000 }
  }'

Response

A 202 means the request is accepted and queued, not that your target has received it.

{
  "queue_id": "hr_9f2a81k2",
  "status": "queued",
  "idempotency_key": "ord_123-paid",
  "created_at": "2026-06-10T14:22:10Z"
}

Status codes

Code	Meaning
`202`	Accepted and queued.
`400`	Invalid request: bad JSON, missing or non-https `target`, or a disallowed method.
`401`	Missing or invalid API key.
`403`	The target domain is not verified for your account.
`429`	Rate limit exceeded. Wait and retry; a `Retry-After` header tells you how long.

Look up what happened to a queued request with the deliveries API.