Webhooks (events) at Stockcrowd.


 
Customer Support
Last Updated: 4 months ago

Let us explain first ?


What are webhooks?


Simply put, webhooks are events that trigger actions. They get their name from the fact that they function as "hooks" for programmes on the Internet and are almost always used for communication between systems. They are the easiest way to issue a warning when a specific event happens on another system.

Below is an introduction and explanation of where they are found and how you can use them within Stockcrowd.

This guide includes the different types of events that StockCrowd triggers and which are used to integrate with web services that retrieve the data associated with each of the events.

Events - Stockcrowd

Types of events


Below is a list of the types of events available in the system:

Payment request confirmed -> This event is triggered when the donation has been confirmed.
Registration confirmed -> This event is triggered when the registration, through a signature form, is confirmed
Reward purchased -> This event is triggered when the reward has been purchased

*There are two events that will be available during 2021:

Abandoned cart -> This event is triggered when a donor has not completed the donation, but we have their details.
Recurrency confirmed -> This event is triggered when the system confirms the amount of a recurring donation


Events Back-Office


The event management back-office is located under the 'Events' menu, in the 'Organisation' section of the StockCrowd back-office.

The steps to define an event are as follows:

  1. Select the type of event to configure
  2. Configure the notification, via url or email
  3. Activate the notification

Once the notification is activated the StockCrowd software will launch an event by placing the event data in the configured url or email.


Data type

The encoding type for any event is UTF-8.


For a Confirmed Payment Request event the associated fields are as follows:

Section title

Description

Length

Format

Example Data

Mandatory

EVENT

Event type             

 

       100

Char

 

INVERSOR_PAYMENT_SUCCEEDED

Y

EVENT_ID

Unique identifier of the triggered event

255

Char

 

be4fceab-1ff8-4ab8-ad5b-4e711be88766                 

Y

FECHA

Registration date

20

Date

2016-04-31 13:00:14

Y

EMAIL

Email account used in registration

255

varChar

user1@domain1.com   

Y

NOMBRE

Name used by the user in the registration process

255

Char

Pedro

Y

APELLIDOS

Surname used by the user in the registration process (Used in forms where the second surname is not required)

255

Char

Duque

Y

CAMPAIGN_TITULO

Campaign title

255

Char

Cohete a la luna

Y

PRIMER_APELLIDO

First surname used by the user in the registration process (Used in forms where the second surname is required)

255

Char

Duque

Y

SEGUNDO_APELLIDO

Second last name used by the user in the registration process (Used in forms where the second last name is required)

255

Char

Pérez

N

PREFIJO_TELEFONO

Telephone prefix entered by the user

5

Char

+34

N

ID_SOLICITUD

Request Unique Identifier (StockCrowd)

20

Num

456

Y

PASARELA_PAGO

Payment gateway used (PayPal, Stripe, Braintree, Lemon Way, Unnax)

100

Varchar

Stripe

Y

TRANSACTION_ID

Transaction identifier depending on the gateway (GATEWAY_PAYMENT)

255

Varchar

ch_1C9uu3BLADaPkItAiAGS1jCI

Y

ORDER_ID

StockCrowd payment request order number (unique). In case of successive requests, it should be checked that it has not been processed previously. This can happen when a contribution goes from anonymous to a registered user.

100

Varchar

879a9792-2b2f-49ca-bf03-1ab6d299e424

Y

IMPORTE

Amount in campaign currency

20

Num

49.95

Y

DIVISA

Currency (CAD, CHF, EUR, GBP, PLN, USD)

3

Varchar

EUR

Y

CAMPAIG_ID

Identifier of the campaign where the payment was made

12

Num

1234

Y

DOCUMENTO

Identity document NIE, DNI, CIF, PASSPORT. * Available if the user requests a SEPBLAC donation or validation certificate

20

Num

41125179Y

Y

TELEFONO

Telephone. * Available if the user requests a SEPBLAC donation or validation certificate

25

Num

612123123

N

DIRECCION

Address. * Available if the user requests a SEPBLAC donation or validation certificate

255

Varchar

C/ Bruc

N

CODIGO_POSTAL

Postal Code. * Available if the user requests a SEPBLAC donation or validation certificate

10

Varchar

08037

N

CIUDAD

City. * Available if the user requests a SEPBLAC donation or validation certificate

100

Varchar

Barcelona

N

PROVINCIA

Province. * Available if the user requests a SEPBLAC donation or validation certificate

50

Varchar

Barcelona

N

ID_PROVINCIA

Province Code. * Available if the user requests a SEPBLAC donation or validation certificate

10

Varchar

08

N

PAIS

Country. * Available if the user requests a SEPBLAC donation or validation certificate

105

Varchar

España

N

ID_PAIS

Country code. * Available if the user requests a SEPBLAC donation or validation certificate

2

Varchar

ES

N

TIPO_DOCUMENTO

Type of identity document (PASSPORT, DNI, CIF, NIF, NIE, OTHERS). * Available if the user requests a SEPBLAC donation or validation certificate

25

Varchar

DNI / CIF / NIE / OTRO

N

TIPO_PERSONA

F = Physical / J = Legal. * Available if the user requests a SEPBLAC donation or validation certificate

805

Varchar

F,N,P = Persona Física

J,E = Persona jurídica

N

RAZON_SOCIAL

If TIPO_PERSONA = J (Legal). * Available if the user requests a SEPBLAC donation or validation certificate

255

Varchar

StockCrowd Fanraising S.L.

N

ACEPTA_PUBLICIDAD

S = Yes | N = No

805

Varchar

S= Yes

N= No

Y

POLITICA_PRIVACIDAD

S = Yes | N = No

805

Varchar

S= Yes

N= No

Y

USUARIO_REGISTRADO_PAYPAL

S = Yes | N = No. If the payment has been made via PayPal and you have used a registered user account.

35

Varchar

S= Yes

N= No

Y

NUMERO_PISO_LETRA

Número, piso y letra de la dirección del donante

150

Varchar

145, Entresuelo 2ª

N

IBAN

ex: # 135, E-2da

150

Varchar

ES55 1251 4161 1165 5165 7323

N

IBAN_TITULAR

IBAN_TITULAR - IBAN holder in payment data capture mode for CRMs

150

Varchar

Pedro Duque

N

PERIODICIDAD

Donation: ON TIME, MONTHLY, QUARTERLY, ANNUAL

30

Varchar

PUNTUAL, MENSUAL, TRIMESTRAL, ANUAL

N

UTM_SOURCE

UTM_SOURCE

200

Varchar

Google

N

UTM_MEDIUM

UTM_MEDIUM

200

Varchar

cpc

N

UTM_CAMPAIGN

UTM_CAMPAIGN

200

Varchar

spring_sale

N

UTM_TERM

UTM_TERM

200

Varchar

running+shoes

N

UTM_CONTENT

UTM_CONTENT

200

Varchar

logolink

N

EXTERNAL_ID

Value of the external identifier field of general campaign data

200

Varchar

SC45X22

N

CATEGORIA

General data category selector value of the campaign

200

Varchar

Ventas

N

SUB_CATEGORIA

Value of the sub-category field of general campaign data

200

Varchar

Electrodomésticos

N

SUBCUENTA_DEBE

Value of the sub-account field must of general campaign data

200

Varchar

45600

N

SUBCUENTA_HABER

Value of the sub-account field of general campaign data

200

Varchar

45700

N

TPV

Value of the general data POS field of the campaign

200

Varchar

45700

N

PAGO_RECURRENTE

S = Yes | N = No. If it corresponds to a recurring charge

200

Varchar

S

N

PAGO_RECURRENTE_FCH_ALTA

Date the initial payment was made

200

Date

2016-04-31 13:00:14

N

PAGO_RECURRENTE_ORDER_ID

ORDER_ID referring to the initial payment

80

Varchar

879a9792-2b2f-49ca-bf03-1ab6d299e123

N

PAYMENT_TOKEN

Payment token for Stripe, Paypal, Sepa, Sofort operations

150

Varchar

tok_1CuGtMHCXJNKLeGQWDNzgDuG

N

SOLICITA_CERTIFICADO_DONACION

S = Yes | N = No. If you have requested a donation certificate

805

Varchar

S

N

LOCALE

User language in IETF BCP 47 format

10

Varchar

es-ES

N

FUNDRAISER_NOMBRE

Name of the creator of the p2p campaign

255

Varchar

Jhon Doe

N


For a Confirmed Registration event the associated fields are as follows:

Section Title

Description

Length

Format

Example Data

Mandatory

EVENT

Event type

100

Char

 

INVERSOR_PAYMENT_SUCCEEDED

Y

EVENT_ID

Unique identifier of the triggered event

255

Char

 

be4fceab-1ff8-4ab8-ad5b-4e711be88766                 

Y

FECHA

Registration date of information associated with the reward from BOFAN

20

Date

2016-04-31 13:00:14

Y

EMAIL

Email account of the user who has purchased and completed the reward

255

varChar

user1@domain1.com   

Y

NOMBRE

Name of the user who starts the payment process

255

Char

Pedro

Y

APELLIDOS

Surname of the user who made the payment

255

Char

Duque

Y

CAMPAIGN_TITULO

Campaign title

255

Char

Cohete a la luna

Y

PRIMER_APELLIDO

First last name used of the user who has made the payment (Used in forms where the second last name is required)

255

Char

Duque

Y

SEGUNDO_APELLIDO

Second last name used of the user who has made the payment (Used in forms where the second last name is required)

255

Char

Pérez

N

PREFIJO_TELEFONO

Telephone prefix entered by the user

5

Char

+34

N

ID_SIGNATURE

Unique signature identifier (StockCrowd)

20

Num

456

S

CAMPAIG_ID

Campaign identifier for the payment request

12

Num

1234

S

DOCUMENTO

Identity document NIE, DNI, CIF, PASSPORT. * Available if the user requests a SEPBLAC donation or validation certificate

20

Num

41125179Y

N

TELEFONO

Telephone. * Available if the user requests a SEPBLAC donation or validation certificate

25

Num

612123123

N

DIRECCION

Address. * Available if the user requests a SEPBLAC donation or validation certificate

255

Varchar

C/ Bruc

N

CODIGO_POSTAL

Postal Code. * Available if the user requests a SEPBLAC donation or validation certificate

10

Varchar

08037

N

CIUDAD

City. * Available if the user requests a SEPBLAC donation or validation certificate

100

Varchar

Barcelona

N

PROVINCIA

Province. * Available if the user requests a SEPBLAC donation or validation certificate

50

Varchar

Barcelona

N

ID_PROVINCIA

Province Code. * Available if the user requests a SEPBLAC donation or validation certificate

10

Varchar

08

N

PAIS

Country. * Available if the user requests a SEPBLAC donation or validation certificate

105

Varchar

España

N

ID_PAIS

Country code. * Available if the user requests a SEPBLAC donation or validation certificate

2

Varchar

ES

N

TIPO_DOCUMENTO

Type of identity document (PASSPORT, DNI, CIF, NIF, NIE, OTHERS). * Available if the user requests a SEPBLAC donation or validation certificate

25

Varchar

DNI / CIF / NIE / OTRO

N

TIPO_PERSONA

F = Physical / J = Legal. * Available if the user requests a SEPBLAC donation or validation certificate

805

Varchar

F,N,P = Persona Física

J,E = Persona jurídica

N

RAZON_SOCIAL

If TIPO_PERSONA = J (Legal). * Available if the user requests a SEPBLAC donation or validation certificate

255

Varchar

StockCrowd Fanraising S.L.

N

ACEPTA_PUBLICIDAD

S = Yes | N = No

805

Varchar

S= Sí

N= No

Y

POLITICA_PRIVACIDAD

S = Yes | N = No

805

Varchar

S= Sí

N= No

Y

NUMERO_PISO_LETRA

ex: # 135, E-2da

150

Varchar

145, Entresuelo 2ª

N

ACEPTA_PUBLICACION_DATOS

S = Yes | N = No

805

Varchar

S

Y

DESCRIPCION

In some cases, the description associated with a signature collection will be indicated.

255

Varchar

Carrer del Bruc 145

N

 

For a Purchased Reward event the associated fields are as follows:

Section Title

Description

Length

Format

Example Data

Mandatory

CHARSET

character encoding format 

Char

UTF-8

Y

EVENT

Event type

100

Char

RECOMPENSA_SOLD

Y

EVENT_ID

Unique identifier of the triggered event

255

Char

be4fceab-1ff8-4ab8-ad5b-4e711be88766

Y

FECHA

Registration date

20

Date

2016-04-31 13:00:14

Y

ID_SOLICITUD_RECOMPENSA

Unique identifier of the triggered event

12

Num

121

Y

ID_RECOMPENSA_DETALLE

Registration date of information associated with the reward from BOFAN

12

Num

206

Y

EMAIL

Email account of the user who has purchased and completed the reward

255

Varchar

user1@domain1.com

Y

NOMBRE

Name of the user who starts the payment process

255

Char

Pedro o Pedro Duque

Y

ID_CAMPAIGN_RECOMPENSA

Requested Reward ID

255

Num

805

Y

TITULO_RECOMPENSA

Reward title

50

Varchar

Camiseta personalizada

Y

DIRECCION_RECOGIDA_ENTREGA

Pickup or delivery address

50

Varchar

Paseo de la castellana

N

ORDER_ID

Order number corresponding to the payment

36

Varchar

33a86073-ab05-4b1e-81b4-7bbcfdca31ed

Y

CANTIDAD

Quantity of units to be delivered

10

Num

3

Y

Data recovery web service configuration

Description of the process of event capture and validation via URL:

  1. Event validation.
    Events are validated by sending a request back to StockCrowd with all the parameters received in the POST. StockCrowd then compares the original event parameters with those received to ensure that the information is correct. If the validation process is correct, the system returns an "OK" in the body of the request and if, on the contrary, the validation is not correct, ERROR is returned in the body of the request.
  2. Checking StockCrowd's response.
    Confirmation to StockCrowd that the event has been processed correctly. If the response is correct, the data is validated and ready to be processed by the system managing the web service.
  3. Confirmation to StockCrowd that the event has been successfully processed.
    This is achieved by sending an "OK" as part of the response body. When StockCrowd sends an event to the URL configured in the notifications, the response is checked to ensure that the URL is actually managed by the domain owner. If the response is correct, the event is not sent again, but if it is not correct, the system will reprocess the event again by making two more requests with a time interval of 24 hours.

Validation URLs depending on the environment:

Testing platform (sandbox) : https://sandbox.stockcrowd.com/api/events/confirm

Production platform (producción): https://www.stockcrowd.com/api/events/confirm

Sample code for event validation

// *** STEP 805 ***

// endpoint de validación StockCrowd

 

$url = 'https://sandbox.stockcrowd.com/api/events/confirm'; // entorno de pruebas

// $url = 'https://www.stockcrowd.com/api/events/confirm'; // entorno de producción

 

// POST de vuelta a StockCrowd con todos los parámetros recibidos

$context = stream_context_create(array(

        'http' => array(

               'method' => 'POST',

               'header' => 'Content-type: application/x-www-form-urlencoded',

               'content' => http_build_query( $_POST )

        )

        , 'timeout' => 60

));

 

// *** STEP 2 ***

$resp = file_get_contents($url, FALSE, $context);

// si la respuesta a la validación por parte de StockCrowd es correcta

if ($resp=='OK'){

        // código de integración propio del cliente (integración con otros sistemas del tipo CRM...)

} else {

        // log para investigar peticiones que no han sido enviadas por StockCrowd

}

 

// *** STEP 3 ***

print_r('OK'); // indicar a StockCrowd que se ha procesado el evento

 

 


Was this article helpful?