Webhooks are an essential tool for managing card activity and responding to events in real-time. By subscribing to webhook notifications, you can receive real-time updates on your card's activity and take appropriate action, such as updating records or triggering workflows.

To use card webhooks, you'll need to set up an endpoint on your server that can receive webhook notifications. Once an event occurs on Raven Atlas, it will send a JSON payload to your endpoint, which you can then process and take appropriate action. To set up a webhook, you'll need to provide a URL for your endpoint, as well as any additional configuration parameters required.

📘

Read more about webhook setup and configuration.

Introduction to webhooks

There are many potential use cases for card webhooks, including:

1. Transaction monitoring: You can use webhooks to receive notifications for each transaction made with your card, allowing you to monitor your card's activity in real time.

2. Fraud detection: By monitoring your card's activity in real time, you can quickly detect suspicious transactions and take action to prevent fraudulent charges.

3. Account management: Webhooks can be used to keep your account up to date with the latest information about your card's status, balance, and more.

To use card webhooks, you'll need to set up an endpoint on your server to receive the webhook notifications. When an event occurs on the server, the server will send a JSON payload to your endpoint, which you can then process and take appropriate action.

Some guidelines to keep in mind when working with Atlas card webhooks include:

• Ensure that your webhook endpoint is secure and can handle large volumes of traffic.
• Handle errors and retries gracefully, since webhooks may be retried multiple times if there are issues with the initial request.
• Verify the authenticity of the webhook requests to ensure that they are coming from the raven card endpoint and not from a malicious actor.

Overall, Raven Atlas card webhooks is a powerful tool that can help you keep track of your card's activity in real time and take action quickly when necessary.

Here is a breakdown of the currently available webhook event types :

1. card_credit_event.successful: This webhook event is triggered when a credit transaction on the virtual card is successful. The payload includes information such as the card ID, transaction amount, currency, transaction reference, and card transaction type.

2. 3d_secure_otp_event.generated: This webhook event is triggered when a card transaction requires a 3D secure OTP authentication. The payload includes information such as the card ID, transaction amount, currency, last four digits of the card, OTP value, transaction date, transaction timestamp, and merchant name.

3. card_debit_event.declined: This webhook event is triggered when a debit transaction on the virtual card is declined. The payload includes information such as the card ID, transaction amount, currency, decline reason, card PAN, and transaction date.

4. card_debit_event.successful: This webhook event is triggered when a debit transaction on the virtual card is successful. The payload includes information such as the card ID, transaction amount, currency, transaction reference, card transaction type, merchant category code, and card PAN.

These webhook events can be used to monitor and track activity on the virtual card, and can be integrated with various third-party applications such as accounting and expense management tools. When integrating with these applications, the guidelines for handling sensitive card information must be followed to ensure the security of the users' data.

Payload Samples

Card Successful Credit Transaction

{
  "meta": {
    "card_id": "5b19d9f0263c42e19fcc54e7b36b0c4c",
    "currency": "USD",
    "amount": 3,
    "card_pan": "434362****2259",
    "transaction_reference": "202302151116BGJIIJD",
    "card_transaction_type": "CREDIT"
  },
  "secret": "secretkey",
  "card_id": "5c19d9f0263c42e19fcc54e7b36b0c4c",
  "type": "card_credit_event.successful"
}

Generated 3DS Authorisation OTP

{
  "meta": {
    "card_id": "289076bcf2504e5080bbb7be938d1a94",
    "currency": "USD",
    "amount": 10,
    "last_four_digits": "8194",
    "otp": "971588",
    "transaction_date": "2023-02-14 15:01:00",
    "transaction_timestamp": "1676386860",
    "card_pan": "432362****7648",
    "merchant_name": "SLACK"
  },
  "secret": "your_secret_key",
  "card_id": "199076bcf2504e5080bbb7be938d1a93",
  "type": "3d_secure_otp_event.generated"
}

Card Transaction declined

{
  "meta": {
    "card_id": "289076bcf2504e5080bbb7be938d1a94",
    "currency": "USD",
    "amount": 280.26,
    "description": "SLACKT03904125N3",
    "transaction_date": "2023-02-14 14:03:48",
    "transaction_timestamp": "1676383428",
    "decline_reason": "Insufficient balance on your card to make this purchase.",
    "card_pan": "434362****7648"
  },
  "secret": "your_secret_key",
  "card_id": "289076bcf2504e5080bbb7be938d1a94",
  "type": "card_debit_event.declined"
}

Card Successful Debit Transaction

{
  "meta": {
    "card_id": "289076bcf2504e5080bbb7be938d1a94",
    "currency": "USD",
    "amount": 10,
    "description": "SLACK IRL",
    "card_pan": "474362****7648",
    "card_transaction_type": "DEBIT",
    "merchant_category_code": "5734",
    "transaction_reference": "fbd66d6e-578e-4af7-a47d-f6c43c33ff60"
  },
  "secret": "your_secret_key",
  "card_id": "289076bcf2504e5080bbb7be938d1a94",
  "type": "card_debit_event.successful"
}

Collections Webhook Payload Example

{
  "type":"collection",
  "amount":300,
  "session_id":"000012221112104439180319952000",
  "account_number":"43453232423",
  "source":
   		{
        "account_number":"0435646022",
        "first_name":"JANE",
        "last_name":"DOE",
        "narration":"Jane Doe ",
        "bank":"POLARIS BANK",
        "bank_code":"000012",
         "createdAt":"2022-11-12 9:46:8"
      },
 	"secret":"your_secret_key"
}