Webhooks

Webhooks allow your applications to receive notifications of activity on your Pin Payments account. You specify a URL, and any time an event occurs (such as a transfer being made to your bank account), Pin Payments will request that URL with details of the event.

When you create a webhook endpoint—that is, when you specify a URL for Pin Payments to request—a signing key is generated. Every webhook request includes a cryptographic signature (technically a message authentication code) based on this signing key; your server can verify it to determine whether the request originated from someone who knew the signing key (presumably Pin Payments).

Creating webhook endpoints through the dashboard

Webhook endpoints can be created through your dashboard.

Navigate to Account and select Webhooks. Add the URL you want Pin Payments to request when events occur on your account. Up to five webhook endpoints can be created, and Pin Payments will send a request to each endpoint when an event occurs.

Managing webhooks through the API

There are methods available in the API for creating, managing and deleting webhook endpoints. You can find the documentation in our webhook endpoints API documentation.

You can also use the API to retrieve the details of webhook requests made to your application in the past. Further information is available in the webhooks API documentation.

Checking the authenticity of a webhook request

Each webhook request made by Pin Payments includes a “Pin-Signature” HTTP header. This allows your server to verify the request’s origin, timestamp and integrity. The header’s value will look like this: t=1500452255,v1=f07f5d147c613d85b9607d1c6b8c15fc342eca4d2cfaaf546f8dded19a30c350. It’s composed of two sub-values, t and v1, separated by a comma.

To verify a signature, your application should concatenate the timestamp sub-value (t), the dot character (“.”) and the body of the webhook request, and then calculate the HMAC of the result using the SHA-256 hash function and the signing key for the endpoint. If the result matches the v1 sub-value, then the signature is valid.

Your application should not necessarily accept all valid signatures. It might reject a valid signature if the timestamp is too old, for example.