Inbound Webhooks

Inbound webhooks let external services create records in a HASP app by POSTing signed JSON to a unique URL. The token in the URL addresses the webhook; the HMAC signature on each request authenticates it.

Inbound webhooks are the one place you call the Data API directly — no SDK is needed because the caller is an external service, not your app’s JavaScript.

Endpoint

POST /api/hasp/v1/incoming/{token}

The {token} is the full plaintext token shown in the HASP dashboard when you create the webhook. No X-Hasp-AppId header or session cookie is needed — the token identifies both the app and the target entity. The token is an address, not a credential: every request must also carry a valid signature (see Signing). Max body size: 256 KB.

Signing

Every request must be signed with the webhook’s signing secret, shown once in the dashboard when you create the webhook. Requests without a valid signature are rejected with 401 UNAUTHORIZED and no record is created. The scheme is HMAC-SHA256 over the timestamp and the raw request body:

Take the current Unix time in seconds as timestamp.
Build the signed string "{timestamp}.{raw_body}" — the timestamp, a literal ., then the exact bytes you send as the body.
Compute the HMAC-SHA256 of that string keyed by the signing secret, hex-encoded.
Send two headers:

Header	Value
`X-Webhook-Signature`	`sha256=<hex digest>`
`X-Hasp-Webhook-Timestamp`	`timestamp` (Unix seconds)

If you configured a custom signature header on the webhook, send the signature in that header instead of X-Webhook-Signature. The timestamp header name does not change. The timestamp must be within ±300 seconds of HASP’s clock; anything older or further in the future is rejected, so a captured request cannot be replayed later. Because the body is part of the signed string, changing either the body or the timestamp invalidates the signature — sign the bytes exactly as you send them. Rotating the secret: after you rotate the signing secret, requests signed with the previous secret are still accepted for 7 days, so you can roll the new secret out to your sender without dropping requests. If the webhook has an IP allowlist, requests from any other address are rejected with 403 IP_NOT_ALLOWED before the signature is checked.

import { createHmac } from 'crypto';

const body = JSON.stringify({ name: 'Alice', email: '[email protected]' });
const timestamp = Math.floor(Date.now() / 1000).toString();
const signature = createHmac('sha256', process.env.HASP_WEBHOOK_SECRET)
  .update(`${timestamp}.${body}`)
  .digest('hex');

// webhookUrl: the full inbound URL shown in the dashboard
await fetch(webhookUrl, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Webhook-Signature': `sha256=${signature}`,
    'X-Hasp-Webhook-Timestamp': timestamp,
  },
  body,
});

import hashlib, hmac, json, os, time
import requests

body = json.dumps({"name": "Alice", "email": "[email protected]"})
timestamp = str(int(time.time()))
signature = hmac.new(
    os.environ["HASP_WEBHOOK_SECRET"].encode(),
    f"{timestamp}.{body}".encode(),
    hashlib.sha256,
).hexdigest()

# webhook_url: the full inbound URL shown in the dashboard
requests.post(
    webhook_url,
    data=body,
    headers={
        "Content-Type": "application/json",
        "X-Webhook-Signature": f"sha256={signature}",
        "X-Hasp-Webhook-Timestamp": timestamp,
    },
)

Idempotency

Include an X-Idempotency-Key header (max 255 characters) to prevent duplicate records from replayed or retried requests. HASP caches the response for 24 hours — repeat requests with the same key return the original response without creating a second record.

Request

POST /api/hasp/v1/incoming/wh_01JA...
Content-Type: application/json
X-Webhook-Signature: sha256=<hex HMAC-SHA256 of "1767225600.{body}">
X-Hasp-Webhook-Timestamp: 1767225600
X-Idempotency-Key: my-unique-key-123

{
  "name": "Alice",
  "email": "[email protected]",
  "source": "contact-form"
}

The body must be a JSON object. Any other body (malformed or truncated JSON, a JSON array or scalar, form-encoded or plain text, or an empty body) is rejected with 422 INVALID_PAYLOAD, and no record is created. A rejected body does not consume its X-Idempotency-Key, so a corrected retry with the same key is processed normally. Keys are mapped to entity field keys according to the webhook’s field mapping (if configured). Unmapped keys are passed through directly. Keys that do not match any entity field are silently dropped.

Response

201 Created:

{
  "data": {
    "record_id": "01JQRECORD00000000000000"
  }
}

Error Responses

HTTP	Code	When
401	`UNAUTHORIZED`	Signature or timestamp header missing, signature invalid, or timestamp outside ±300 seconds
403	`IP_NOT_ALLOWED`	Request origin is not in the webhook’s IP allowlist
404	`NOT_FOUND`	Token not found or webhook is inactive
413	`PAYLOAD_TOO_LARGE`	Body exceeds 256 KB
422	`INVALID_PAYLOAD`	Body is not a JSON object
422	`VALIDATION_FAILED`	Payload fails entity schema validation
422	`ERROR`	Quota exceeded or processing error

Loop Prevention

If the request contains an X-Hasp-Webhook-Id header (set automatically on all outbound webhook deliveries), the record.created event is not re-dispatched. This prevents outbound → inbound → outbound infinite loops.

Field Mapping

When creating an inbound webhook in the dashboard, you can configure a field mapping to translate incoming key names to your entity’s field keys. Unmapped keys are passed through as-is.

AI Studio

Platform

AI API

Data API

App Builder SDK

Inbound Webhooks

Endpoint

Signing

Idempotency

Request

Response

Error Responses

Loop Prevention

Field Mapping

​Endpoint

​Signing

​Idempotency

​Request

​Response

​Error Responses

​Loop Prevention

​Field Mapping

Endpoint

Signing

Idempotency

Request

Response

Error Responses

Loop Prevention

Field Mapping