Primer Docs

Get notified about payment updates

A Webhook is a notification sent from Primer to your server. Webhooks will notify you of:

payment status updates
This is especially useful for asynchronous processor Connections, which do not respond with an upfront authorization.
opened disputes/chargebacks
Be notified of disputes across all processors in a unified way.
completed refunds
Primer notifies you when a refund request has been fully processed by a payment processor and the refund has reached a final state.

webhooks

Setting up webhooks

Set up a Webhook in the Developers area of the Dashboard. Webhooks are sent with a POST request to your designated endpoint.

add a webhook

Failed notification attempts are retried up to three times with a five-second interval.

Field	Description
eventType	The type of event that triggered the webhook. This will have the value `DISPUTE.OPENED`. This indicates that a dispute notification or chargeback was issued through a configured connection. The easiest actions you can take are to proactively communicate with your customer and issue refunds where appropriate, especially when requested.
primerAccountId	A unique identifier for your Primer merchant account.
transactionId	A unique identifier for the Primer transaction corresponding to this dispute.
orderId	Your reference for the sale transaction that the dispute relates to.
processorId	The name of the processor that generated the dispute.
processorDisputeId	A unique identifier for the corresponding connection dispute.
paymentId	A unique identifier for the Primer payment corresponding to this dispute.

Even if you already listen to the Payment status updates webhooks, consuming this additional webhook is strongly encouraged if you use Capture or Cancel via Workflows, as a failure to capture or cancel will neither fail the payment itself nor lead to an update of the payment status. Not knowing that a capture or cancel failed could therefore result in unintended consequences.

Full details available within the Automation documentation: Workflow Run failed webhook.

1234567891011121314151617181920212223{    "eventType": "WORKFLOW_RUN.FAILED",    "version": "1.0",    "date": "2024-02-21 15:36:16.167687",    "primerAccountId": "123abcde-99f2-416e-8013-6ecd1c1285c3",    "triggerEventId": "DdRZ6YY0",    "workflow": {        "id": "ecb8d3bc-123a-4d56-826e-ef8d4cc3d2a2",        "name": "MIT UK Card",        "version" : 8    },    "run": {        "timestamp": "2024-03-07T12:20:14.394429",        "id": "bbb1c3cc-805d-4d97-826e-ef8d4cc3d2a2",        "status": "FAILED",        "lastError": {            "applicationId": "PRIMER_PAYMENTS",            "actionId": "capture_payment",            "diagnosticsId": "1234567890",            "message": "Payment ID not found."        }    }}

json

copy

Webhook signing

Primer can sign all webhook notification events before they are sent to your server, allowing you to verify that the events were sent by us and not anyone else. This is achieved by adding a X-Signature-Primary header to each event, after which you can verify the signature.

How does it work?

A X-Signature-Primary header is added to all webhook events and is a HMAC signature generated using the webhook payload and a shared signing secret. This is then converted to a base64 encoded string.

The shared signing secret is generated by Primer and is unique to your account (details below). You will use this secret to validate the signature sent by Primer.

When you have rotated your secret, a X-Signature-Secondary header will also be added. See more below.

Avoid replay attacks

Inside the webhook payload there is an additional field signedAt to indicate the Unix timestamp of when the webhook was signed.

Use this timestamp to drastically reduce the chance of a replay attack. Because the timestamp is included in the payload, the same payload cannot be sent with a different timestamp without causing an invalid signature.

When verifying the signature, you should also validate that the timestamp is within an acceptable threshold from your current system time (in unix epoch format). Primer recommends a threshold of up to 3 minutes.

If Primer retries sending the webhook notification event, the timestamp at the time of sending the retried event is used, so each attempt would have a new timestamp and therefore a new hash.

Verifying the signature

To ensure that a webhook notification did indeed come from Primer, you need to compute the hash of the payload and compare that with the value in the header.

Below is an example of doing exactly this.

1234567891011121314151617181920212223242526272829import base64import hashlibimport hmac
SHARED_SECRET = 'OYCTN7OTUBE2CX3EBGB5QABJBFUXWD3A'  # Hardcoded for demonstration. Use an environment variable or secrets vault in production.WEBHOOK_PAYLOAD = '{"eventType": "PAYMENT.STATUS", "date": "2023-09-14 16:30:35.059215", "notificationConfig": {"id": "d9ad7ba8-97fa-4364-9aec-16ddb3c68b86", "description": "2.2"}, "payment": {"id": "ov1370cHi", "date": "2023-09-14T16:30:34.696933", "dateUpdated": "2023-09-14T16:30:34.696933", "amount": 100, "currencyCode": "EUR", "customerId": "Primer", "orderId": "1234", "status": "PENDING", "customer": {}, "paymentMethod": {"paymentType": "UNSCHEDULED", "authorizationType": "FINAL", "paymentMethodToken": "xGMIxQcIT32FwXsve_2UnnwxNjk0NzA5MDMz", "isVaulted": false, "analyticsId": "7qBrd-64V6ucGeNHm7KNjkFO", "paymentMethodType": "PAYMENT_CARD", "paymentMethodData": {"last4Digits": "1111", "first6Digits": "411111", "expirationMonth": "03", "expirationYear": "2030", "cardholderName": "MR FOO BAR", "network": "Visa", "binData": {"network": "VISA", "issuerCountryCode": "US", "issuerName": "JPMORGAN CHASE BANK, N.A.", "regionalRestriction": "NONE", "accountNumberType": "PRIMARY_ACCOUNT_NUMBER", "accountFundingType": "DEBIT", "prepaidReloadableIndicator": "NOT_APPLICABLE", "productUsageType": "CONSUMER", "productCode": "VISA", "productName": "VISA"}, "isNetworkTokenized": false}}, "processor": {"name": "STRIPE", "processorMerchantId": "acct_1GORcsGZqNWFwi8c", "amountCaptured": 0, "amountRefunded": 0}, "transactions": []}, "version": "2.2", "signedAt": "1694709036"}'WEBHOOK_SIGNATURE = 'aYgNWDnUmNZOA7EGWgU3cZk8YrDa4AIyuio85YhSswQ='

def validate_webhook_signature(webhook_payload: str, webhook_signature: str, shared_secret: str) -> bool:    mac = hmac.new(        key=shared_secret.encode("utf-8"),        msg=webhook_payload.encode("utf-8"),        digestmod=hashlib.sha256,    )    computed_signature = base64.b64encode(mac.digest()).decode("utf-8").strip()
    # Verify the hash matches the signature from the header    return computed_signature == webhook_signature

def __main__():    if validate_webhook_signature(WEBHOOK_PAYLOAD, WEBHOOK_SIGNATURE, SHARED_SECRET):        print("Webhooks match!")    else:        print("Webhooks do NOT match!")

__main__()

python

copy

Set up your signing secret

Primer allows you to generate a unique signing secret key for all your webhook notification events for a specific environment (i.e. one for Sandbox and one for Production). After you have completed the setup (see below), Primer starts to sign each webhook it sends to your endpoints.

First, navigate to the Webhooks section on the Developers page of the Primer Dashboard. Then, select the Webhook signing button.

create webhook secret 2

Now you need to select the create signing secret button which will then generate your new signing secret.

create webhook secret 1

Once generated, your new signing secret will be shown.

This is your only chance to copy it, so make sure you store it somewhere safe!

create webhook secret 3

From this point, we will add the signature to all your webhook events and you can verify the signature to confirm the events are coming from Primer and not anyone else.

Rotate your signing secret

You can rotate the active signing secret from the Primer Dashboard at your discretion.

When a secret is rotated, the previous secret will remain active for 24 hours. During this period you will receive two signature headers and can verify against either.

X-Signature-Primary → The payload hashed with the new signing secret
X-Signature-Secondary → The payload hashed with the previous signing secret

This will give you time to update the stored signing secret within your application before the previous signing secret expires.

First, select the webhook signing button on the Webhooks section of the Developer page in the Primer Dashboard.

create webhook secret 4

Then, select the Regenerate secret button.

create webhook secret 5

A popup will then appear asking you to confirm you want to regenerate your signing secret. If you’re sure you want to proceed, select the Regenerate secret button.

This is an irreversible action so make sure you want to confirm the rotation of your signing secret.

create webhook secret 6

You will then be shown your new signing secret.

This is your only chance to copy it, so make sure you copy and paste it somewhere safe!

create webhook secret 7

Both signatures will be included in the webhook header for 24 hours to give you time to update the stored signing secret in your application.

When setting up handling the webhook events from Primer, it’s recommended to check for both headers so that you don’t experience any disruption when you rotate your signing secret.

1234567891011121314@router.post(    "/my-webhook",)async def my_webhook(    request: Request,    primer_payload: dict):    if "X-Signature-Primary" in request.headers:        _validate_webhook_signature(request.headers["X-Signature-Primary"], primer_payload)
    if "X-Signature-Secondary" in request.headers:        _validate_webhook_signature(request.headers["X-Signature-Secondary"], primer_payload)
    # Process webhook...

python

copy

This way, you will only need to update the stored secret within 24 hours and no further action will be needed.

Get notified about payment updates

Setting up webhooks

Testing webhooks

Webhook types

Status updates

Refunds

Disputes & chargebacks

Workflow Run failed

Webhook signing

How does it work?

Avoid replay attacks

Verifying the signature

Set up your signing secret

Rotate your signing secret