Events Reference

This page documents every webhook event type that amser dispatches. Each event follows a common envelope structure and contains a data object with event-specific fields.

Common Envelope

Every webhook payload is wrapped in a common envelope:

{
  "id": "550e8400-e29b-51d4-a716-446655440000",
  "type": "payment.succeeded",
  "created_at": 1710000000,
  "livemode": true,
  "data": { }
}

Field	Type	Description
`id`	string	Deterministic UUID v5 derived from chain, transaction hash, and log index. Stable across retries — use this for idempotency.
`type`	string	The event type (e.g. `payment.succeeded`).
`created_at`	integer	Unix timestamp (seconds) when the event was created.
`livemode`	boolean	`true` for production events, `false` for testnet.
`data`	object	Event-specific payload. Structure varies by event type.

Common Data Fields

Every data object includes these operational fields in addition to the event-specific fields documented below:

Field	Type	Description
`tx_hash`	string	Transaction hash of the on-chain event.
`block_number`	integer	Block number containing the transaction.
`log_index`	integer	Log index within the transaction.
`chain_id`	integer	Chain ID where the event occurred.

Payment Events

Payment events fire when a keeper executes a payment through the PaymentProcessor, regardless of which module type originated it.

`payment.succeeded`

A payment was executed and funds were transferred from the payer to the recipient.

Emitted by: SubscriptionModule, CreditModule

{
  "id": "550e8400-e29b-51d4-a716-446655440000",
  "type": "payment.succeeded",
  "created_at": 1710000000,
  "livemode": true,
  "data": {
    "module_address": "0x1234567890abcdef1234567890abcdef12345678",
    "subscription_id": "42",
    "payer": "0xaabbccddee1122334455667788990011aabbccdd",
    "recipient": "0x9988776655443322110011223344556677889900",
    "token": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "amount": "5000000",
    "protocol_fee": "50000",
    "keeper_fee": "25000",
    "keeper": "0xdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef",
    "executed_at": 1710000000,
    "tx_hash": "0xabc123...",
    "block_number": 19000000,
    "log_index": 3,
    "chain_id": 11155111
  }
}

`payment.failed`

A payment execution was attempted but failed. Common causes include insufficient balance, expired allowance, or a paused subscription.

Emitted by: SubscriptionModule, CreditModule

{
  "id": "661f9511-f3ac-52e5-b827-557766551111",
  "type": "payment.failed",
  "created_at": 1710000300,
  "livemode": true,
  "data": {
    "module_address": "0x1234567890abcdef1234567890abcdef12345678",
    "subscription_id": "42",
    "payer": "0xaabbccddee1122334455667788990011aabbccdd",
    "recipient": "0x9988776655443322110011223344556677889900",
    "token": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "amount": "0",
    "protocol_fee": "0",
    "keeper_fee": "0",
    "keeper": "0xdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef",
    "executed_at": 1710000300,
    "reason": "InsufficientBalance",
    "is_final": false,
    "tx_hash": "0xdef456...",
    "block_number": 19000001,
    "log_index": 5,
    "chain_id": 11155111
  }
}

Field	Type	Description
`reason`	string	Machine-readable failure reason (e.g. `InsufficientBalance`, `InsufficientAllowance`, `Paused`).
`is_final`	boolean	`true` if the failure is non-retryable (e.g. `Paused`, `InsufficientAllowance`). `false` if the keeper may retry.

Subscription Events

Subscription events fire when the state of a subscription changes within a SubscriptionModule.

`subscription.created`

A new subscription was created. The subscriber has signed a Permit2 authorization and the subscription is now ready for first payment.

Emitted by: SubscriptionModule

{
  "id": "772a0622-04bd-53f6-c938-668877662222",
  "type": "subscription.created",
  "created_at": 1710001000,
  "livemode": true,
  "data": {
    "module_address": "0x1234567890abcdef1234567890abcdef12345678",
    "subscription_id": "42",
    "subscriber": "0xaabbccddee1122334455667788990011aabbccdd",
    "plan_id": "1",
    "tx_hash": "0x111aaa...",
    "block_number": 19000010,
    "log_index": 0,
    "chain_id": 11155111
  }
}

`subscription.paused`

A subscription was paused by the subscriber. No payments will be executed while paused.

Emitted by: SubscriptionModule

{
  "id": "883b1733-15ce-54g7-da49-779988773333",
  "type": "subscription.paused",
  "created_at": 1710002000,
  "livemode": true,
  "data": {
    "module_address": "0x1234567890abcdef1234567890abcdef12345678",
    "subscription_id": "42",
    "subscriber": "0xaabbccddee1122334455667788990011aabbccdd",
    "plan_id": "1",
    "paused_at": 1710002000,
    "tx_hash": "0x222bbb...",
    "block_number": 19000020,
    "log_index": 1,
    "chain_id": 11155111
  }
}

`subscription.resumed`

A previously paused subscription was resumed by the subscriber.

Emitted by: SubscriptionModule

{
  "id": "994c2844-26df-55h8-eb50-880099884444",
  "type": "subscription.resumed",
  "created_at": 1710003000,
  "livemode": true,
  "data": {
    "module_address": "0x1234567890abcdef1234567890abcdef12345678",
    "subscription_id": "42",
    "subscriber": "0xaabbccddee1122334455667788990011aabbccdd",
    "plan_id": "1",
    "resumed_at": 1710003000,
    "tx_hash": "0x333ccc...",
    "block_number": 19000030,
    "log_index": 2,
    "chain_id": 11155111
  }
}

`subscription.executions_exhausted`

All authorized execution windows for the subscription have been used. The subscription has reached its natural end. This event is derived from database state — it fires after a payment.succeeded or payment.failed event when the subscription's remaining executions reach zero.

Emitted by: SubscriptionModule (derived)

{
  "id": "aa5d3955-37e0-56i9-fc61-991100995555",
  "type": "subscription.executions_exhausted",
  "created_at": 1710006000,
  "livemode": true,
  "data": {
    "module_address": "0x1234567890abcdef1234567890abcdef12345678",
    "subscription_id": "42",
    "subscriber": "0xaabbccddee1122334455667788990011aabbccdd",
    "plan_id": "1",
    "total_executions": 12,
    "tx_hash": "0x444ddd...",
    "block_number": 19000040,
    "log_index": 3,
    "chain_id": 11155111
  }
}

Envelope Events

Envelope events fire when the state of a credit envelope changes within a CreditModule. Envelopes represent allocated credit budgets for agents.

`envelope.created`

A new credit envelope was created. The user has allocated credits to an agent.

Emitted by: CreditModule

{
  "id": "bb6e4a66-48f1-57j0-0d72-aa2211aa6666",
  "type": "envelope.created",
  "created_at": 1710007000,
  "livemode": true,
  "data": {
    "module_address": "0xabcdef1234567890abcdef1234567890abcdef12",
    "envelope_id": "7",
    "subscriber": "0xaabbccddee1122334455667788990011aabbccdd",
    "plan_id": "3",
    "tx_hash": "0x555eee...",
    "block_number": 19000050,
    "log_index": 0,
    "chain_id": 84532
  }
}

`envelope.settled`

A credit envelope was settled. Consumed credits have been paid for and the envelope is closed.

Emitted by: CreditModule

{
  "id": "cc7f5b77-59g2-58k1-1e83-bb3322bb7777",
  "type": "envelope.settled",
  "created_at": 1710008000,
  "livemode": true,
  "data": {
    "module_address": "0xabcdef1234567890abcdef1234567890abcdef12",
    "envelope_id": "7",
    "subscriber": "0xaabbccddee1122334455667788990011aabbccdd",
    "plan_id": "3",
    "settled_at": 1710008000,
    "sequence": "3",
    "credits_used": "1500",
    "tx_hash": "0x666fff...",
    "block_number": 19000060,
    "log_index": 1,
    "chain_id": 84532
  }
}

`envelope.refilled`

A credit envelope was refilled with additional credits by the user.

Emitted by: CreditModule

{
  "id": "dd8g6c88-6ah3-59l2-2f94-cc4433cc8888",
  "type": "envelope.refilled",
  "created_at": 1710009000,
  "livemode": true,
  "data": {
    "module_address": "0xabcdef1234567890abcdef1234567890abcdef12",
    "envelope_id": "7",
    "subscriber": "0xaabbccddee1122334455667788990011aabbccdd",
    "plan_id": "3",
    "refilled_at": 1710009000,
    "tx_hash": "0x777ggg...",
    "block_number": 19000070,
    "log_index": 0,
    "chain_id": 84532
  }
}

`envelope.paused`

A credit envelope was paused. No further credit consumption or settlement will occur until resumed.

Emitted by: CreditModule

{
  "id": "ee9h7d99-7bi4-50m3-3g05-dd5544dd9999",
  "type": "envelope.paused",
  "created_at": 1710010000,
  "livemode": true,
  "data": {
    "module_address": "0xabcdef1234567890abcdef1234567890abcdef12",
    "envelope_id": "7",
    "subscriber": "0xaabbccddee1122334455667788990011aabbccdd",
    "plan_id": "3",
    "paused_at": 1710010000,
    "tx_hash": "0x888hhh...",
    "block_number": 19000080,
    "log_index": 2,
    "chain_id": 84532
  }
}

`envelope.resumed`

A previously paused credit envelope was resumed.

Emitted by: CreditModule

{
  "id": "ff0i8e00-8cj5-51n4-4h16-ee6655ee0000",
  "type": "envelope.resumed",
  "created_at": 1710011000,
  "livemode": true,
  "data": {
    "module_address": "0xabcdef1234567890abcdef1234567890abcdef12",
    "envelope_id": "7",
    "subscriber": "0xaabbccddee1122334455667788990011aabbccdd",
    "plan_id": "3",
    "resumed_at": 1710011000,
    "tx_hash": "0x999iii...",
    "block_number": 19000090,
    "log_index": 0,
    "chain_id": 84532
  }
}

Event Type Summary

Event	Description	Module
`payment.succeeded`	Payment executed and funds transferred	SubscriptionModule, CreditModule
`payment.failed`	Payment execution attempted but failed	SubscriptionModule, CreditModule
`subscription.created`	New subscription created	SubscriptionModule
`subscription.paused`	Subscription paused by subscriber	SubscriptionModule
`subscription.resumed`	Paused subscription resumed	SubscriptionModule
`subscription.executions_exhausted`	All execution windows used	SubscriptionModule
`envelope.created`	New credit envelope created	CreditModule
`envelope.settled`	Credit envelope settled and closed	CreditModule
`envelope.refilled`	Credit envelope refilled	CreditModule
`envelope.paused`	Credit envelope paused	CreditModule
`envelope.resumed`	Paused credit envelope resumed	CreditModule

Next Steps

Implement Signature Verification to validate incoming events
Review the Retry Behaviour to handle delivery failures gracefully
Set up an API Key to authenticate your server-side requests

Common Envelope​

Common Data Fields​

Payment Events​

payment.succeeded​

payment.failed​

Subscription Events​

subscription.created​

subscription.paused​

subscription.resumed​

subscription.executions_exhausted​

Envelope Events​

envelope.created​

envelope.settled​

envelope.refilled​

envelope.paused​

envelope.resumed​

Event Type Summary​

Next Steps​

Common Envelope

Common Data Fields

Payment Events

`payment.succeeded`

`payment.failed`

Subscription Events

`subscription.created`

`subscription.paused`

`subscription.resumed`

`subscription.executions_exhausted`

Envelope Events

`envelope.created`

`envelope.settled`

`envelope.refilled`

`envelope.paused`

`envelope.resumed`

Event Type Summary

Next Steps