Aurigraph Event Subscriptions deliver on-chain events to your systems two ways: HMAC-signed webhooks with retries, exponential backoff and a dead-letter queue, and a gRPC server-streaming feed that can replay history from an offset and then continue live. Both read from one transactional outbox, so an event exists only if the state change that produced it committed.
Availability. Event Subscriptions, including per-party event scoping, are part of the Aurigraph V12 platform. Check that your target environment runs a build that includes it before integrating: a node that predates the merge answers 404 on /api/v11/event-subscriptions.
404
/api/v11/event-subscriptions
Six event types are shipped. Each has a real emitter that writes the event in the same database transaction as the change itself.
data
TOKEN_TRANSFERRED
OWNERSHIP_TRANSFER
COMPOSITE_TOKEN_TRANSFERRED
CONTRACT_BOUND
CONTRACT_CREATED
CONTRACT_STATE_CHANGED
List the catalogue from a running node with GET /api/v11/event-subscriptions/event-types.
GET /api/v11/event-subscriptions/event-types
eventTypes
CONTRACT_*
*
ERR_EVENTSUB_002
assetId
A webhook subscription, the live gRPC stream and a gRPC replay all apply the same rule. An event is delivered to a caller only when:
admin
compliance-officer
auditor
toAddress
fromAddress
from_offset = 0
UNAVAILABLE
All paths are under /api/v11/event-subscriptions and require an authenticated caller with the USER, ENTERPRISE or ADMIN role.
USER
ENTERPRISE
ADMIN
GET /event-types
POST /
201
GET /
GET /{id}
DELETE /{id}
204
GET /{id}/deliveries?status=&limit=
limit
status
PENDING
IN_FLIGHT
DELIVERED
DEAD
CANCELLED
GET /{id}/dlq
POST /{id}/dlq/replay
{"replayed": n}
POST /{id}/dlq/{deliveryId}/replay
409 ERR_EVENTSUB_005
Create request fields: name (optional, up to 128 characters), targetUrl (required), eventTypes, assetId, and maxAttempts (optional, 1 to 20, default 8).
name
targetUrl
maxAttempts
# Create a subscription curl -X POST https://dlt.aurigraph.io/api/v11/event-subscriptions \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "transfer-monitor", "targetUrl": "https://hooks.example.com/aurigraph", "eventTypes": ["TOKEN_TRANSFERRED", "OWNERSHIP_TRANSFER", "CONTRACT_*"], "assetId": "RWA-RE-001", "maxAttempts": 8 }' # 201: { "subscription": { "subscriptionId": "...", "status": "ACTIVE", ... }, # "secret": "whsec_...", "signatureHeader": "X-Aurigraph-Signature", # "signatureScheme": "t=<unix-seconds>,v1=hex(HMAC-SHA256(secret, t + \".\" + body))" } # Store the secret now. It is not shown again. # Inspect and operate curl -H "Authorization: Bearer $TOKEN" https://dlt.aurigraph.io/api/v11/event-subscriptions curl -H "Authorization: Bearer $TOKEN" "https://dlt.aurigraph.io/api/v11/event-subscriptions/$SUB_ID/deliveries?status=DEAD" curl -X POST -H "Authorization: Bearer $TOKEN" https://dlt.aurigraph.io/api/v11/event-subscriptions/$SUB_ID/dlq/replay curl -X DELETE -H "Authorization: Bearer $TOKEN" https://dlt.aurigraph.io/api/v11/event-subscriptions/$SUB_ID
https
422 ERR_EVENTSUB_003
503 ERR_EVENTSUB_007
Each delivery is a POST with Content-Type: application/json and this body, identical on every attempt:
POST
Content-Type: application/json
{ "id": "0b6f6c0e-3f0e-4d55-9a53-7c2f1f7b9d11", "type": "TOKEN_TRANSFERRED", "offset": 1042, "assetId": "RWA-RE-001", "occurredAt": "2026-10-18T08:30:00Z", "data": { "tokenId": "RWA-RE-001", "toAddress": "0x...", "shares": 10, "txRef": "..." } }
Headers: X-Aurigraph-Event-Id, X-Aurigraph-Event-Type, X-Aurigraph-Delivery-Id (stable across retries and replays), X-Aurigraph-Attempt, X-Aurigraph-Timestamp and X-Aurigraph-Signature.
X-Aurigraph-Event-Id
X-Aurigraph-Event-Type
X-Aurigraph-Delivery-Id
X-Aurigraph-Attempt
X-Aurigraph-Timestamp
X-Aurigraph-Signature
X-Aurigraph-Signature: t=<unix-seconds>,v1=<lowercase-hex>, where v1 = HMAC-SHA256(key = secret as UTF-8, message = t + "." + raw request body).
X-Aurigraph-Signature: t=<unix-seconds>,v1=<lowercase-hex>
v1 = HMAC-SHA256(key = secret as UTF-8, message = t + "." + raw request body)
import hmac, hashlib, time def verify(secret: str, header: str, raw_body: bytes, tolerance: int = 300) -> bool: parts = dict(p.split("=", 1) for p in header.split(",")) t, v1 = parts["t"], parts["v1"] mac = hmac.new(secret.encode(), t.encode() + b"." + raw_body, hashlib.sha256).hexdigest() return hmac.compare_digest(mac, v1) and abs(time.time() - int(t)) <= tolerance
Verify against the raw bytes exactly as received. The timestamp is inside the MAC; choose your own tolerance (300 seconds above is an example, not a platform value).
2xx
min(1h, 10s x 2^(attempt-1))
offset
Service aurigraph.v11.events.EventStreamService, one server-streaming method, Subscribe(EventStreamRequest) returns (stream OnChainEvent). The proto is event_subscriptions.proto in the V12 source. The caller must be authenticated (Bearer JWT or ApiKey metadata, as on every V12 gRPC service); an anonymous call fails with UNAUTHENTICATED.
aurigraph.v11.events.EventStreamService
Subscribe(EventStreamRequest) returns (stream OnChainEvent)
event_subscriptions.proto
UNAUTHENTICATED
message EventStreamRequest { repeated string event_types = 1; // exact, PREFIX_* or "*"; empty = every type string asset_id = 2; // empty = any asset optional int64 from_offset = 3; // replay after this offset } message OnChainEvent { int64 offset = 1; string event_id = 2; string event_type = 3; string asset_id = 4; string occurred_at = 5; string payload_json = 6; }
grpcurl -proto event_subscriptions.proto \ -H "Authorization: Bearer $TOKEN" \ -d '{"event_types": ["CONTRACT_*"], "from_offset": 0}' \ <grpc-host>:9004 aurigraph.v11.events.EventStreamService/Subscribe
from_offset
from_offset = N
N
0
INVALID_ARGUMENT
event_id
409 ERR_EVENTSUB_006
RESOURCE_EXHAUSTED
Errors are RFC 7807 application/problem+json; the codes are registered in the platform error-code registry.
application/problem+json
ERR_EVENTSUB_001
ERR_EVENTSUB_003
ERR_EVENTSUB_004
ERR_EVENTSUB_005
ERR_EVENTSUB_006
ERR_EVENTSUB_007
ERR_EVENTSUB_008
gRPC failures use status codes: UNAUTHENTICATED, INVALID_ARGUMENT (bad filter or negative from_offset) and RESOURCE_EXHAUSTED.
Explore: About · Products · Features · Whitepapers · Sustainability · Tokenized carbon credits · Real-world asset tokenization · SDK · Blog · Plain-text site index · Sitemap · Contact: contact@aurigraph.io