Integrations

Webhooks

Receive real-time notifications when events happen on your agent identities. Webhooks deliver JSON payloads to your endpoint for inbound emails, SMS messages, card transactions, wallet transfers, and more.

Webhook setup

Register a webhook endpoint via the API or the Humiris dashboard. You specify which events to subscribe to and an optional agent filter. Humiris will send an HTTP POST to your URL every time a matching event occurs.

bash

# Create a webhook
curl -X POST https://api.humiris.com/v1/webhooks \
  -H "Authorization: Bearer hum_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/hooks/humiris",
    "events": ["email.received", "sms.received", "card.authorization"],
    "agent": null
  }'

# Response
{
  "id": "whk_a2b4c6",
  "url": "https://yourapp.com/hooks/humiris",
  "events": ["email.received", "sms.received", "card.authorization"],
  "signing_secret": "whsec_k9m2x4...",
  "status": "active"
}

Set the agent field to a specific agent slug to receive events only for that agent, or set it to null to receive events for all agents in your workspace.

Event types

Humiris supports the following webhook event types:

email.receivedNew email arrived in an agent inbox

email.sentOutbound email was successfully delivered

email.bouncedOutbound email bounced

sms.receivedNew SMS received on an agent phone number

sms.sentOutbound SMS was delivered

call.startedInbound or outbound voice call started

call.endedVoice call ended (includes transcript)

card.authorizationCard transaction authorization requested

card.captureCard transaction captured (funds settled)

card.declineCard transaction was declined

card.refundCard transaction was refunded

wallet.transfer.inIncoming crypto transfer received

wallet.transfer.outOutgoing crypto transfer confirmed

agent.createdNew agent was created

agent.deletedAgent was deleted

Verification and signing

Every webhook delivery includes a signature in the X-Humiris-Signature header. Verify this signature using your webhook signing secret to ensure the payload was sent by Humiris and has not been tampered with.

bash

# The signature header format:
# X-Humiris-Signature: t=1712419200,v1=sha256hash...

# The signature is computed as:
# HMAC-SHA256(signing_secret, timestamp + "." + raw_body)

typescript

import crypto from 'crypto';

function verifyWebhook(
  payload: string,
  signature: string,
  secret: string
): boolean {
  const [tPart, vPart] = signature.split(',');
  const timestamp = tPart.replace('t=', '');
  const expectedSig = vPart.replace('v1=', '');

  const computed = crypto
    .createHmac('sha256', secret)
    .update(timestamp + '.' + payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(computed),
    Buffer.from(expectedSig)
  );
}

Retry policy

If your endpoint returns a non-2xx status code or does not respond within 10 seconds, Humiris will retry the delivery. Retries follow an exponential backoff schedule: 30 seconds, 5 minutes, 30 minutes, 2 hours, and 24 hours. After 5 failed attempts, the delivery is marked as failed and visible in the dashboard.

bash

# List recent webhook deliveries
curl https://api.humiris.com/v1/webhooks/whk_a2b4c6/deliveries \
  -H "Authorization: Bearer hum_sk_live_..."

# Replay a failed delivery
curl -X POST https://api.humiris.com/v1/webhooks/whk_a2b4c6/deliveries/dlv_x8y2z4/retry \
  -H "Authorization: Bearer hum_sk_live_..."

Next steps

Generate an API Key to authenticate webhook management. Explore Agent Email, Agent Phone, and Agent Card for the primitives that generate webhook events. See the API Reference for the full webhooks API.