Use webhooks to integrate MonetizeNow with with your platform or other external service.

Configuring Events

Go to Settings > Webhooks > and click New
Provide an HTTP endpoint that accepts POST events where messages will be sent
Click "Select Events" and choose the events that you would like to subscribe to

Webhook Events

The following webhook events are supported and will be sent using a POST request to the endpoint you configure.

Entity	Event	Occurs When
Account	account.created	an account is created
	account.updated	an account is updated
Contact	contact.created	a contact is created
	contact.updated	a contact is updated
Quote	quote.created	a quote is created
	quote.updated	a quote is updated
	quote.accepted	a quote is accepted
	quote.processed	a quote is processed
	quote.cancelled	a quote is cancelled
	quote.offering.created	an offering is added to a quote
	quote.offering.updated	an offering on a quote is updated
	quote.offering.deleted	an offering is deleted from a quote
Opportunity	opportunity.created	an opportunity is created
	opportunity.updated	an opportunity is updated
Offering	offering.created	an offering is created
	offering.updated	an offering is updated
Contract	contract.created	a contract is created
	contract.updated	a contract is updated
Rate	rate.created	a rate is created
	rate.updated	a rate is updated
	rate.deleted	a rate is deleted
	price.deleted	a rate's price is deleted
Bill Group	dunning.step.tiggered	a dunning step is triggered
Invoice	invoice.created	an invoice is created
	invoice.paid	an invoice is paid
Subscription	subscription.created	a subscription is created
	subscription.created.summary	a subscription is created, with a smaller payload
	subscription.updated	a subscription is updated
	subscription.updated.summary	a subscription is updated, with a smaller payload
	subscription.status.changed	a subscription status is changed

Request Payload

Events follow the structure listed below. You are expected to respond with a 200 response code to acknowledge that the event was successfully received.

Review the full list of Payload Examples

{
    "eventId": "whevt_YqhTdhCn55LXqkMsZ8Hb3fdv",
    "userId": "usr_qDf2afaOyHShW2oGZ",
    "sentTime": "2023-01-01T00:00:00.956607265Z",
    "eventType": "subscription.updated",
    "data": { ... }
}

Request Headers

Each webhook event will have the following headers included in the request

Name	Description	Example
x-monetizenow-signature	Signature generated with webhooks secret and event payload	`PDDVvixLI7g/Vs89Rkzv7hSfOHhW+tk0YvTPD03e66E="`
x-tenant-id	Tenant ID of MonetizeNow tenant where the event originated.	`tennt_tydX1aEVHymLYoDs`
x-user-id	User ID of the MonetizeNow user triggering the webhook event.	`usr_qDfP1rOyHShW2oGZ`

Signature Verification

MonetizeNow signs the webhook events it sends to your registered endpoints by including a header X-MonetizeNow-Signature with each request. This allows you to verify that the request to your endpoint came from MonetizeNow and not a third-party. To verify the signature:

Extract the signature from the header X-MonetizeNow-Signature.
Extract the UTF-8 text payload as bytes.
Compute a HMAC with the SHA256 hash function, using your webhook entry's secret as the key and the request payload bytes as the message.
Base64-encode the HMAC digest and compare this value to the signature header to check for equivalence.

Verifying the request will vary depending on your programming language.

const sig = Buffer.from(req.get('x-monetizenow-signature'), 'base64');
const hmac = crypto.createHmac('sha256', secret);
const digest = Buffer.from(hmac.update(req.rawBody).digest('base64'), 'base64');
const verified = crypto.timingSafeEqual(digest, sig);

bytes = request.get_data();
sentHash = request.headers.get('x-monetizenow-signature');
computedHash = hmac.new(secret, msg=bytes, digestmod=hashlib.sha256)
verified = sentHash == base64.b64encode(computedHash.digest())

fun base64Encode(bytes: ByteArray) = Base64.getEncoder().encodeToString(bytes)

fun hmac256(
  key: String,
  data: String,
): ByteArray {
  val digest = "HmacSHA256"
  val mac = Mac.getInstance(digest)
  mac.init(
    SecretKeySpec(
      key.toByteArray(Charsets.UTF_8),
      digest
    )
  )
  return mac.doFinal(data.toByteArray(Charsets.UTF_8))
}

fun isSignatureValid(
  requestSignature: String,
  webhookSecret: String,
  stringifiedPayload: String,
): Boolean {
	val generatedSignature = base64Encode(
    bytes = hmac256(
      key = webhookSecret,
      data = stringifiedPayload,
    ),
  )
  return generatedSignature == requestSignature
}

Delivery attempts and retries

In the event that MonetizeNow receives a non-2xx response status from an endpoint, the delivery will be tried up to 3 times, with a minimum backoff of 5 seconds in between attempts.