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

Webhook event object

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.
account.number.update	An Account’s number has been updated
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.
entity_attribute.credit_health_credit_card_usage_value.increased	Credit card usage has increased.
entity_attribute.credit_health_credit_card_usage_value.decreased	Credit card usage has decreased.
entity_attribute.credit_health_derogatory_marks_value.increased	Number of derogatory marks increased.
entity_attribute.credit_health_derogatory_marks_value.decreased	Number of derogatory marks decreased.
entity_attribute.credit_health_hard_inquiries_value.increased	Number of hard inquiries increased.
entity_attribute.credit_health_hard_inquiries_value.decreased	Number of hard inquiries decreased.
entity_attribute.credit_health_total_accounts_value.increased	Total number of accounts increased.
entity_attribute.credit_health_total_accounts_value.decreased	Total number of accounts decreased.
entity_attribute.credit_health_credit_age_value.increased	Credit age has increased.
entity_attribute.credit_health_credit_age_value.decreased	Credit age has decreased.
entity_attribute.credit_health_payment_history_value.increased	Payment history score has improved.
entity_attribute.credit_health_payment_history_value.decreased	Payment history score has decreased.
entity_attribute.credit_health_soft_inquiries_value.increased	Number of soft inquiries increased.
method_jwk.create	A new Method JWK (public key) was successfully created.
method_jwk.update	A Method JWK has been updated (deprecated or disabled).

THE WEBHOOK OBJECT

{
  "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 EVENT OBJECT

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