Docs
Guides
Explanatory and how-to content
API Reference
Technical documentation
Changelog
Release notes
Dashboard
Manage your account
Status
Service status
Guides
Overview
Products

Events and webhooks

When something interesting happens on your Increase account, such as a new Transaction being created, Increase can reach out to your application so that you can take action (such as sending an email alert about the transaction to your user) automatically.

The first step is to create an Event Subscription in the dashboard or via the API. As part of this, you specify a URL on your own servers. Increase will then send HTTPS requests to that URL to notify you of activity.

When something noteworthy happens, Increase first generates an Event object. Next, we’ll send a POST request to your endpoint. The body of the POST request will be the same as the API representation of the Event, such as:

{
  "id": "event_123abc",
  "created_at": "2020-01-31T23:59:59Z",
  "category": "transaction.created",
  "associated_object_type": "transaction",
  "associated_object_id": "transaction_abc123",
  "type": "event"
}

Note that you can make Event Subscriptions in the live API or in the sandbox. Sandbox Event Subscriptions will receive webhooks for Sandbox Events and vice versa.

Consuming Events

Individual Events don’t contain very much information on their own. This is by design, as the API structure can remain extremely stable and avoid difficult webhook migrations in the future as the Increase API changes. If you need additional metadata, such as the amount of the Transaction in the above example, make a GET request to the API for that information. You can use the associated_object_type or category fields to determine what resource to fetch from the API.

If you don’t want to use webhooks, or if you need batch processing, you can also request Events from the Increase API using the List Events API. In fact, we recommend polling over webhooks for data synchronization.

You can access Events for up to 30 days.

Failures and retries

In production, if your application returns anything other than a 20x HTTP status code, we’ll retry it up to 7 times with exponentially increasing backoffs. In your webhook endpoint implementation, we recommend you place inbound Events into your application’s own queuing system (such as Kafka, Resque, etc) for asynchronous event processing, and returning a 200 response from your endpoint as quickly as possible. Because we can’t guarantee we’ll receive your 200, your webhook implementation should gracefully handle receiving the same webhook multiple times.

To avoid queueing issues, we will not retry failed webhooks in the sandbox.

Event types

For a list of all of the possible actions that will result in an Event being generated and a webhook being sent, see our API reference.

You can configure your Webhook to receive all of the events, or a single specific category.

IP addresses

We currently send webhooks from these IP addresses:

  • 34.83.67.223
  • 35.247.122.129
  • 34.168.16.194

OAuth webhooks

If you operate an OAuth application, you can subscribe to webhooks in your users’ account. More details are in the OAuth guide.

Securing your webhook endpoint (recommended)

Increase uses the Standard Webhooks specification for webhook signatures. Each webhook request includes three headers for verification:

  • webhook-id: A unique identifier for the webhook message (the Event ID)
  • webhook-timestamp: Unix timestamp (seconds since epoch) when the webhook was sent
  • webhook-signature: The signature(s) for verifying authenticity
webhook-id: event_123abc
webhook-timestamp: 1674087231
webhook-signature: v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=

Increase generates signatures using a hash-based message authentication code (HMAC) with SHA-256, then Base64-encodes the result. The signature is prefixed with the version v1,.

Using a Standard Webhooks library

The easiest way to verify webhook signatures is to use a Standard Webhooks library. Libraries are available for many languages including JavaScript, Python, Ruby, Go, Java, and more.

Manual verification

If you prefer to verify signatures manually, follow these steps:

Step 1: Extract the headers

Extract the webhook-id, webhook-timestamp, and webhook-signature headers from the request.

Step 2: Prepare the signed payload

The signed payload is created by concatenating:

  • The webhook-id value
  • The character .
  • The webhook-timestamp value
  • The character .
  • The raw request body (JSON payload)

For example: event_123abc.1674087231.{"id":"event_123abc",...}

Step 3: Compute the expected signature

Compute an HMAC-SHA256 using your endpoint’s signing secret as the key and the signed payload as the message. Then Base64-encode the result and prefix it with v1,.

Step 4: Compare signatures

Compare the computed signature to each signature in the webhook-signature header (signatures are space-separated when multiple secrets are active during rotation). Use a constant-time string comparison to protect against timing attacks.

Also verify that the webhook-timestamp is within an acceptable time window (e.g., 5 minutes) to prevent replay attacks. You can use the webhook-id as an idempotency key to prevent processing duplicate webhooks.