Webhooks

Getting Started

Atom allows you to create several webhooks which can each be subscribed to any number of different message types. Follow the steps below to set up a webhook.

1. Visit the webhooks tab on the Atom Admin Portal.
2. Select 'Add new webhook' and enter the full url that you would like the messages to be delivered to.
3. Choose the message types that you would like to receive and click 'Save'. If you do not see the message types that you are looking for, please reach out to your Atom representative.
4. Toggle on the 'Enabled' switch to start receiving messages.
5. At this stage your webhook should be receiving content, but before using it in production you should verify that messages sent to your webhook are sent from Atom by using your HMAC secret for sender verification.

👍

Return a 200 status code

Be sure to return a 200 status code when your webhook receives a message, otherwise the same message will be resent after a delay, and your webhook may automatically be disabled after failing to return any 200 status codes for over 24 hours.

Webhook Data Shape

Webhook messages that you receive from Atom will all have the following general shape:

{
  "messageType": "test",
  "data": [],
  "timestamp": 1657834328221,
}

• messageType will specify the type of data that you have received and help you decide what to do with the data. The possible values are shown in the table below.
• data field will always be an array of objects. The type of objects will differ based on the messageType.
• timestamp field shows the time (in unix epoch milliseconds) that the message was sent.

Using your HMAC secret for message verification

Our webhooks use HMAC signatures for message verification. Each message that Atom sends to your webhook will be signed with a signature that is generated by combining the body of the request with your HMAC secret, allowing you to verify that messages you receive are indeed sent by Atom.

To verify a signature you need to:

1. Read the entire request body as an array of bytes.
2. Generate the HMAC signature using your HMAC secret, the body of the request, and SHA256.
3. Read the x-atom-signature header that is attached to the request.
4. Make sure both signatures are base64 encoded, and verify that they are equal. (You should use a timing-safe function for comparison to protect against a timing based attack).

const crypto = require('crypto');

function verifySignature(request) {
  const signature = request.headers['x-atom-signature'];

  const computedSignature = crypto
    .createHmac('sha256', HMAC_SECRET)
    .update(JSON.stringify(request.body))
    .digest("base64");

  return computedSignature.length === signature.length &&
    crypto.timingSafeEqual(
      Buffer.from(computedSignature, 'utf-8'),
      Buffer.from(signature, 'utf-8')
    );
}

import hmac, hashlib, base64

def generate_signature(secret, payload):
    secret_bytes = str.encode(secret)
    hash_bytes = hmac.new(secret_bytes, msg=payload, digestmod=hashlib.sha256).digest()
    signature = base64.b64encode(hash_bytes)
    return signature.decode("utf-8")
  
 def verify_signature(request_body, request_headers):
    signature = request_headers['x-atom-signature']
    computed_signature = generate_signature(HMAC_SECRET, request_body)
    return hmac.compare_digest(signature, computed_signature)