Webhooks

The webhook proxy provides reliable outbound webhook delivery through HiveForge, with automatic retries, HMAC-SHA256 signing, idempotency support, and delivery tracking.

Access the webhook proxy via hiveforge.webhooks.

import { HiveForgeClient } from '@producthacker/hiveforge-sdk';
 
const hiveforge = new HiveForgeClient({
  deploymentId: process.env.HIVEFORGE_DEPLOYMENT_ID!,
  deploymentSecret: process.env.HIVEFORGE_DEPLOYMENT_SECRET!,
});
await hiveforge.initialize();

Methods

`send(options)`

Send a webhook through HiveForge's delivery service. The service automatically retries failed deliveries with exponential backoff (up to 3 attempts).

const result = await hiveforge.webhooks.send({
  url: 'https://api.partner.com/webhooks/orders',
  payload: {
    event: 'order.created',
    data: {
      orderId: 'ord_8a7b6c5d4e3f',
      amount: 9999,
      currency: 'usd',
      customer: 'cus_P1q2R3s4T5u6V7w8',
    },
  },
  eventType: 'order.created',
  secret: 'whsec_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6',
});
 
console.log('Success:', result.success);
console.log('Webhook ID:', result.webhookId);
console.log('Status code:', result.statusCode);
console.log('Attempts:', result.attempts);
console.log('Delivered at:', result.deliveredAt);
console.log('Credits used:', result.creditsUsed);

With custom headers and idempotency:

await hiveforge.webhooks.send({
  url: 'https://api.partner.com/webhooks',
  payload: { event: 'user.updated', data: { userId: 'usr_a1b2c3' } },
  method: 'PUT',
  headers: {
    'X-Custom-Header': 'my-value',
    'Authorization': 'Bearer partner_token_xyz',
  },
  idempotencyKey: 'evt_unique_a1b2c3d4',
  eventType: 'user.updated',
});

Parameters (SendWebhookOptions):

Parameter	Type	Required	Default	Description
`url`	`string`	Yes	--	Target URL for webhook delivery
`payload`	`Record<string, unknown>`	Yes	--	JSON payload to send
`method`	`'POST' \| 'PUT' \| 'PATCH'`	No	`'POST'`	HTTP method
`headers`	`Record<string, string>`	No	--	Additional HTTP headers
`secret`	`string`	No	--	Secret for HMAC-SHA256 signing
`eventType`	`string`	No	--	Event type identifier
`idempotencyKey`	`string`	No	--	Idempotency key for deduplication

When a secret is provided, HiveForge signs the webhook payload using HMAC-SHA256 and includes the signature in the request headers. The receiving server can use this to verify the webhook authenticity.

Returns (SendWebhookResponse):

Field	Type	Description
`success`	`boolean`	Whether delivery was successful
`webhookId`	`string`	Unique delivery ID for tracking
`statusCode`	`number`	HTTP status code from the target
`responseBody`	`string`	Response body from the target (truncated)
`error`	`string`	Error message if delivery failed
`creditsUsed`	`number`	Credits consumed
`creditsRemaining`	`number`	Remaining credits
`attempts`	`number`	Number of delivery attempts made
`deliveredAt`	`string`	ISO timestamp of successful delivery

Throws: WebhookProxyException if the delivery setup fails (not for target server errors -- those are returned in the response).

Equivalent curl request

curl -X POST https://api.hiveforge.dev/api/v1/proxy/webhooks/send \
  -H "Content-Type: application/json" \
  -H "X-Deployment-ID: d9f2a1b4-7c3e-4f8a-b5d6-1e2f3a4b5c6d" \
  -H "X-Deployment-Secret: sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
  -d '{
    "url": "https://api.partner.com/webhooks/orders",
    "payload": {"event": "order.created", "data": {"orderId": "ord_8a7b6c5d4e3f"}},
    "method": "POST",
    "event_type": "order.created",
    "secret": "whsec_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
  }'

`getQuota()`

Get webhook delivery quota for your deployment.

const quota = await hiveforge.webhooks.getQuota();
 
console.log(`Credits available: ${quota.creditsAvailable}`);
console.log(`Credits per webhook: ${quota.creditsPerWebhook}`);
console.log(`Webhooks available: ${quota.webhooksAvailable}`);
console.log(`Period ends: ${quota.periodEnds}`);

Returns (WebhookQuotaResponse):

Field	Type	Description
`creditsAvailable`	`number`	Total credits available
`creditsPerWebhook`	`number`	Credit cost per webhook delivery
`webhooksAvailable`	`number`	Number of webhooks that can be sent
`periodEnds`	`string`	Optional ISO timestamp for period end

Error Handling

import { WebhookProxyException } from '@producthacker/hiveforge-sdk';
 
try {
  await hiveforge.webhooks.send({
    url: 'https://api.partner.com/webhooks',
    payload: { event: 'test' },
  });
} catch (error) {
  if (error instanceof WebhookProxyException) {
    console.error(`Webhook error [${error.code}]: ${error.message}`);
 
    if (error.creditsRequired !== undefined) {
      console.log(`Credits required: ${error.creditsRequired}`);
      console.log(`Credits available: ${error.creditsAvailable}`);
    }
  }
}

Types

import type {
  SendWebhookOptions,
  SendWebhookResponse,
  WebhookQuotaResponse,
  WebhookProxyError,
} from '@producthacker/hiveforge-sdk';

Vectors React Components