The webhook endpoint

Webhooks allow the Method API to notify your application when certain events occur. To receive Webhook notifications, create a Webhook by registering a URL pointing to your application where triggered events should be sent to. This URL is where Method will send event information in an HTTPS POST request.

Handling webhooks

A Webhook event is considered successfully delivered when the corresponding URL endpoint responds with an HTTP status code of 200 within 5 seconds. If the criteria is not met, Method will reattempt 4 more times with each new attempt being delayed according to an exponential backoff algorithm, where the delay period between each attempt exponentially increases.

Webhooks that consistently fail to respond with a 200 will automatically be disabled.

Authentication

Webhook Request Validation

We use the auth_token and hmac_secret you provide to enable webhook authentication. There are 2 ways to authenticate an incoming request.

1. Authorization Header Verification

The token for request validation will be sent as a base64-encoded string in the Authorization header of the webhook. You can verify the request originated from Method by base64-encoding your auth_token and comparing it to the incoming header value to ensure the integrity of the event.

const SECRET = 'your-auth-token';
const expected_auth = Buffer.from(SECRET).toString('base64');
const incoming_auth = req.headers['authorization'];

if (incoming_auth !== expected_auth) {
  return res.status(401).send('Invalid Authorization token');
}

2. HMAC Verification

If you provide an hmac_secret when registering your webhook, Method will include a method-webhook-signature header in every request. This is an HMAC-SHA256 digest created using the hmac_secret as the shared secret, and computed over the string timestamp:payload, where timestamp is the value from the method-webhook-timestamp (UNIX timestamp in seconds) header (which is always included, even if no hmac_secret is provided) and payload is the raw request body. Checking for the timestamp freshness (5 min window) is optional, but recommended.

${method-webhook-timestamp}:${raw_payload}

The timestamp is always included in the method-webhook-timestamp header, even if no hmac_secret is provided.

const HMAC_SECRET = 'your-auth-token'; // Replace with the hmac_secret you provided Method
const ts = req.headers['method-webhook-timestamp'];
const hmac_sig = req.headers['method-webhook-signature'];
const msg = `${ts}:${req.rawBody}`;
const expected_sig = crypto.createHmac('sha256', HMAC_SECRET).update(msg).digest('hex');

if (!crypto.timingSafeEqual(Buffer.from(hmac_sig), Buffer.from(expected_sig))) {
  return res.status(401).send('Invalid signature');
}

Example: Minimal Express Server for Verifying Webhooks

import express from 'express';
import crypto from 'crypto';
import bodyParser from 'body-parser';

const app = express();

const SECRET = 'your-auth-token';
const HMAC_SECRET = 'your-hmac-secret'; // Replace with the hmac_secret you provided Method
const expected_auth = Buffer.from(SECRET).toString('base64');

app.use(bodyParser.json({
  verify: (req, _, buf) => req.rawBody = buf.toString(),
}));

app.post('/webhook', (req, res) => {
  const ts = req.headers['method-webhook-timestamp'];
  const hmac_sig = req.headers['method-webhook-signature'];
  const incoming_auth = req.headers['authorization'];

  if (!ts || !sig || !incoming_auth) return res.status(400).send('Missing headers');
  if (incoming_auth !== expected_auth) return res.status(401).send('Invalid Authorization token');
  // 1. check for freshness of the request
  if (Math.abs(Date.now() / 1000 - ts) > 300) return res.status(400).send('Timestamp expired');

  // 2. message reconstruction
  const msg = `${ts}:${req.rawBody}`;
  // 3. compute HMAC 
  const expected_sig = crypto.createHmac('sha256', HMAC_SECRET).update(msg).digest('hex');

  // 4. constant-time comparison
  if (!crypto.timingSafeEqual(Buffer.from(hmac_sig), Buffer.from(expected_sig))) {
    return res.status(401).send('Invalid signature');
  }

  res.status(200).send('Accepted');
});

app.listen(3000, () => console.log('Listening on port 3000'));

Webhook Objects

string

Unique identifier for the Webhook.

type

enum

The event type to be sent to this URL. See Webhook Event Types.

url

string

The URL receiving the webhook event.

metadata

object | null

Additional data provided during creation. See metadata

expand_event

boolean

Whether to expand the event object in the Webhook payload. (default: false)

status

enum

Whether webhook is 'active' or 'disabled'.

error

object | null

An object representing an error that occurred while processing this Webhook. See Webhook errors.

created_at

string

Timestamp of when the Webhook was created.

updated_at

string

Timestamp of when the Webhook was last updated.

Webhook event object

string

The identifier of the resource modified.

type

string

The event type. See Webhook Event Types.

path

string

The URL path pointing to the affected resource. Make a HTTP GET request to this path to retrieve the resource.

Webhook Event Types

Name	Description
`account.create`	A new Account was successfully created.
`account.update`	An Account has been updated.
`account.opened`	An Account has been opened.
`account.closed`	An Account has been closed.
`sensitive.create`	A new Sensitive was successfully created.
`sensitive.update`	An Sensitive has been updated.
`account_verification_session.create`	A new AccountVerificationSession was successfully created.
`account_verification_session.update`	An AccountVerificationSession has been updated.
`balance.create`	A new Balance was successfully created.
`balance.update`	A Balance has been updated.
`card_brand.create`	A new CardBrand was successfully created.
`card_brand.update`	A CardBrand has been updated.
`card_brand.available`	A CardBrand has been made available.
`connect.create`	A new Connect was successfully created.
`connect.update`	A Connect has been updated.
`connect.available`	An Async Connect has completed.
`credit_score.create`	A new CreditScore was successfully created.
`credit_score.update`	A CreditScore has been updated.
`entity.create`	A new Entity was successfully created.
`entity.update`	An Entity has been updated.
`entity_verification_session.create`	A new EntityVerificationSession was successfully created.
`entity_verification_session.update`	An EntityVerificationSession has been updated.
`identity.create`	A new Identity was successfully created.
`identity.update`	An Identity has been updated.
`payment.create`	A new Payment was successfully created.
`payment.update`	A Payment has been updated.
`payment_reversal.create`	A new PaymentReversal was successfully created.
`payment_reversal.update`	A PaymentReversal has been updated.
`payoff.create`	A new Payoff was successfully created.
`payoff.update`	A Payoff has been updated.
`product.create`	A new Product was successfully created.
`product.update`	A Product has been updated.
`report.create`	A new Report was successfully created.
`report.update`	A Report has been updated.
`subscription.create`	A new Subscription was successfully created.
`subscription.update`	A Subscription has been updated.
`transaction.create`	A new Transaction was successfully created.
`transaction.update`	A Transaction has been updated.
`update.create`	A new Update was successfully created.
`update.update`	An Update has been updated.
`credit_score.increased`	A user’s credit score has increased.
`credit_score.decreased`	A user’s credit score has decreased.
`attribute.create`	A new Attribute was successfully created.
`attribute.credit_health_credit_card_usage.increased`	Credit card usage has increased.
`attribute.credit_health_credit_card_usage.decreased`	Credit card usage has decreased.
`attribute.credit_health_derogatory_marks.increased`	Number of derogatory marks increased.
`attribute.credit_health_derogatory_marks.decreased`	Number of derogatory marks decreased.
`attribute.credit_health_hard_inquiries.increased`	Number of hard inquiries increased.
`attribute.credit_health_hard_inquiries.decreased`	Number of hard inquiries decreased.
`attribute.credit_health_total_accounts.increased`	Total number of accounts increased.
`attribute.credit_health_total_accounts.decreased`	Total number of accounts decreased.
`attribute.credit_health_credit_age.increased`	Credit age has increased.
`attribute.credit_health_credit_age.decreased`	Credit age has decreased.
`attribute.credit_health_payment_history.increased`	Payment history score has improved.
`attribute.credit_health_payment_history.decreased`	Payment history score has decreased.
`method_jwk.create`	A new Method JWK (public key) was successfully created.
`method_jwk.update`	A Method JWK has been updated (deprecated or disabled).

{
  "id": "whk_cSGjA6d9N8y8R",
  "type": "payment.update",
  "url": "https://reference.example.app/webhook",
  "metadata": null,
  "expand_event": false,
  "status": "active",
  "error": null,
  "created_at": "2020-12-09T00:41:05.647Z",
  "updated_at": "2020-12-09T00:41:05.647Z"
}

{
  "webhook_id": "whk_cSGjA6d9N8y8R",
  "id": "pmt_zR3nJG3c99P3X",
  "type": "payment.update",
  "op": "update",
  "path": "/payments/pmt_zR3nJG3c99P3X",
  "event": "evt_knqJgxKUnqDVJ",
  "refs": {
    "entity": "ent_qKNBB68bfHGNA"
  }
}

API Reference

Entities

Accounts

Payments

Elements

Events

Supporting Endpoints

Handling webhooks

Authentication

Webhook Objects

Webhook event object

Webhook Event Types

API Reference

Entities

Accounts

Payments

Elements

Events

Supporting Endpoints

​Handling webhooks

​Authentication

​Webhook Objects

​Webhook event object

​Webhook Event Types

Handling webhooks

Authentication

Webhook Objects

Webhook event object

Webhook Event Types